From 2d113bc514913c59ff15bf129d1f764cce2489de Mon Sep 17 00:00:00 2001 From: Marcin Jarczewski Date: Wed, 23 Oct 2024 00:01:41 +0200 Subject: [PATCH] ci: support multiple OpenAPI files --- .github/workflows/ci.yml | 140 +- .spelling | 25 +- openapi/openapi.json | 39908 +++++++++++++++++++++++++++++++++++++ 3 files changed, 40000 insertions(+), 73 deletions(-) create mode 100644 openapi/openapi.json diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 57aa89b8..e2aa262c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,7 +13,7 @@ on: - jp-partial # Run for PRs on main and staging pull_request: - branches: [main, staging] + branches: [ main, staging ] jobs: # The lint job checks that all content is sanitized, @@ -23,19 +23,19 @@ jobs: runs-on: ubuntu-latest timeout-minutes: 10 - # We use node 14 and Python 3.8 + # We use node 18 and Python 3.12 strategy: matrix: - node-version: [14.x] - python-version: [3.8] + node-version: [ 18.x ] + python-version: [ 3.12 ] # The following steps are performed for each lint job steps: - name: Check out the repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v2 + uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} @@ -45,7 +45,7 @@ jobs: pip install yamllint - name: Set up Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} @@ -64,10 +64,10 @@ jobs: if: github.ref == 'refs/heads/main' timeout-minutes: 10 - # We use node 14.X + # We use node 18.X strategy: matrix: - node-version: [14.x] + node-version: [ 18.x ] # Requires the lint and test jobs to pass first needs: @@ -76,29 +76,23 @@ jobs: # The following steps are performed for each job steps: - name: Check out the repo - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Set up Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} - - name: Build content - run: | - yarn install - yarn build:spec - yarn build:content - - name: Push API specification - uses: s0/git-publish-subdir-action@v2.4.0 + uses: s0/git-publish-subdir-action@v2.6.0 env: REPO: self BRANCH: en - FOLDER: compiled/spec + FOLDER: openapi GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Notify other repositories of update - uses: peter-evans/repository-dispatch@v1 + uses: peter-evans/repository-dispatch@v3 with: token: ${{ secrets.REPO_ACCESS_TOKEN }} repository: box/box-postman @@ -106,35 +100,41 @@ jobs: client-payload: "{}" - name: "Trigger Netlify deployment" - uses: joelwmale/webhook-action@2.0.2 + uses: joelwmale/webhook-action@2.4.1 env: WEBHOOK_URL: ${{ secrets.NETLIFY_BOXDEV_WEBHOOK }} data: "{}" - name: "Trigger Netlify deployment (Box.dev mirror)" - uses: joelwmale/webhook-action@2.0.2 + uses: joelwmale/webhook-action@2.4.1 env: WEBHOOK_URL: ${{ secrets.NETLIFY_BOXDEV_MIRROR_WEBHOOK }} data: "{}" - - name: Send Slack notification - uses: Ilshidur/action-slack@2.0.2 - env: - SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }} - SLACK_USERNAME: GitHub Actions - SLACK_AVATAR: "https://avatars3.githubusercontent.com/u/8659759?s=200&v=4" + - name: Send Slack using Slack GHA notification + uses: slackapi/slack-github-action@v1.27.0 with: - args: "Pushed latest OpenAPI changes to `en` branch :rocket:" + payload: | + { + "text": "Pushed latest OpenAPI changes to `en` branch :rocket:", + "icon_url": "https://avatars3.githubusercontent.com/u/8659759?s=200&v=4", + "username": "GitHub Actions" + } + env: + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }} - - name: Send Slack notification - uses: Ilshidur/action-slack@2.0.2 + - name: Send Slack using Slack GHA notification + uses: slackapi/slack-github-action@v1.27.0 if: ${{ failure() }} - env: - SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }} - SLACK_USERNAME: GitHub Actions - SLACK_AVATAR: "https://avatars3.githubusercontent.com/u/8659759?s=200&v=4" with: - args: "Error running `deploy` job in OpenAPI CI" + payload: | + { + "text": "Error running `deploy` job in OpenAPI CI", + "icon_url": "https://avatars3.githubusercontent.com/u/8659759?s=200&v=4", + "username": "GitHub Actions" + } + env: + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }} # The deploy task actually deploys any changes to the en-staging branch push-to-en-staging: @@ -143,10 +143,10 @@ jobs: if: github.ref == 'refs/heads/staging' timeout-minutes: 10 - # We use node 14.X + # We use node 18.X strategy: matrix: - node-version: [14.x] + node-version: [ 18.x ] # Requires the lint and test jobs to pass first needs: @@ -155,50 +155,51 @@ jobs: # The following steps are performed for each job steps: - name: Check out the repo - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Set up Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} - - name: Build content - run: | - yarn install - yarn build:spec - - name: Push API specification - uses: s0/git-publish-subdir-action@v2.4.0 + uses: s0/git-publish-subdir-action@v2.6.0 env: REPO: self - BRANCH: en-staging - FOLDER: compiled/spec + BRANCH: staging + FOLDER: openapi GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: "Trigger Netlify deployment" - uses: joelwmale/webhook-action@2.0.2 + uses: joelwmale/webhook-action@2.4.1 env: WEBHOOK_URL: ${{ secrets.NETLIFY_BOXDEV_STAGING_WEBHOOK }} data: "{}" - - name: Send Slack notification - uses: Ilshidur/action-slack@2.0.2 - env: - SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }} - SLACK_USERNAME: GitHub Actions - SLACK_AVATAR: "https://avatars3.githubusercontent.com/u/8659759?s=200&v=4" + - name: Send Slack using Slack GHA notification + uses: slackapi/slack-github-action@v1.27.0 with: - args: "Pushed latest OpenAPI changes to `en-staging` branch :rocket:" + payload: | + { + "text": "Pushed latest OpenAPI changes to `en-staging` branch :rocket:", + "icon_url": "https://avatars3.githubusercontent.com/u/8659759?s=200&v=4", + "username": "GitHub Actions" + } + env: + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }} - - name: Send Slack notification - uses: Ilshidur/action-slack@2.0.2 + - name: Send Slack using Slack GHA notification + uses: slackapi/slack-github-action@v1.27.0 if: ${{ failure() }} - env: - SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }} - SLACK_USERNAME: GitHub Actions - SLACK_AVATAR: "https://avatars3.githubusercontent.com/u/8659759?s=200&v=4" with: - args: "Error running `deploy-staging` job in OpenAPI CI" + payload: | + { + "text": "Error running `deploy-staging` job in OpenAPI CI", + "icon_url": "https://avatars3.githubusercontent.com/u/8659759?s=200&v=4", + "username": "GitHub Actions" + } + env: + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }} # Build the OpenAPI spec and validate using Codegen validate-spec: @@ -209,17 +210,17 @@ jobs: # The following steps are performed for each job steps: - name: Check out the repo - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: path: box-openapi - - name: Set up Node.js 16.x - uses: actions/setup-node@v3 + - name: Set up Node.js 20.x + uses: actions/setup-node@v4 with: - node-version: 16.x + node-version: 20.x - name: Check out the Codegen repo - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: repository: box/box-codegen ref: main @@ -232,5 +233,4 @@ jobs: npm install cd scripts npm install - cp $GITHUB_WORKSPACE/box-openapi/openapi.json . - npm run generate ./openapi.json output typescript,swift,python,c# + npm run generate $GITHUB_WORKSPACE/box-openapi/openapi/openapi.json output typescript,swift,python,c# diff --git a/.spelling b/.spelling index 699e2bae..e188ca3a 100644 --- a/.spelling +++ b/.spelling @@ -32,7 +32,6 @@ backtick Backticks backticks Backticked -backticked Schema schema Schemas @@ -62,7 +61,27 @@ special org GitHub LLMs -OpenAI +SDKs +openapi +typings config +readme +README +roadmap +changelog +dev +kanban +api +Splunk +runbook +nvm +jwt +box-jwt +Jenkinsfile +onboarding +devpod +inlined +OpenAI AppItem -freeform \ No newline at end of file +freeform +unmarks \ No newline at end of file diff --git a/openapi/openapi.json b/openapi/openapi.json new file mode 100644 index 00000000..969705e9 --- /dev/null +++ b/openapi/openapi.json @@ -0,0 +1,39908 @@ +{ + "openapi": "3.0.2", + "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", + "x-box-commit-hash": "31590ecc71" + }, + "servers": [ + { + "url": "https://api.box.com/2.0", + "description": "Box Platform API server" + } + ], + "paths": { + "/authorize": { + "get": { + "operationId": "get_authorize", + "summary": "Authorize user", + "description": "Authorize a user by sending them through the [Box](https://box.com)\nwebsite and request their permission to act on their behalf.\n\nThis is the first step when authenticating a user using\nOAuth 2.0. To request a user's authorization to use the Box APIs\non their behalf you will need to send a user to the URL with this\nformat.", + "parameters": [ + { + "name": "response_type", + "in": "query", + "description": "The type of response we'd like to receive.", + "required": true, + "schema": { + "type": "string", + "format": "token", + "enum": [ + "code" + ] + }, + "example": "code" + }, + { + "name": "client_id", + "in": "query", + "description": "The Client ID of the application that is requesting to authenticate\nthe user. To get the Client ID for your application, log in to your\nBox developer console and click the **Edit Application** link for\nthe application you're working with. In the OAuth 2.0 Parameters section\nof the configuration page, find the item labelled `client_id`. The\ntext of that item is your application's Client ID.", + "required": true, + "schema": { + "type": "string" + }, + "example": "ly1nj6n11vionaie65emwzk575hnnmrk" + }, + { + "name": "redirect_uri", + "in": "query", + "description": "The URI to which Box redirects the browser after the user has granted\nor denied the application permission. This URI match one of the redirect\nURIs in the configuration of your application. It must be a\nvalid HTTPS URI and it needs to be able to handle the redirection to\ncomplete the next step in the OAuth 2.0 flow.\nAlthough this parameter is optional, it must be a part of the\nauthorization URL if you configured multiple redirect URIs\nfor the application in the developer console. A missing parameter causes\na `redirect_uri_missing` error after the user grants application access.", + "required": false, + "schema": { + "type": "string", + "format": "url" + }, + "example": "http://example.com/auth/callback" + }, + { + "name": "state", + "in": "query", + "description": "A custom string of your choice. Box will pass the same string to\nthe redirect URL when authentication is complete. This parameter\ncan be used to identify a user on redirect, as well as protect\nagainst hijacked sessions and other exploits.", + "required": false, + "schema": { + "type": "string" + }, + "example": "my_state" + }, + { + "name": "scope", + "in": "query", + "description": "A space-separated list of application scopes you'd like to\nauthenticate the user for. This defaults to all the scopes configured\nfor the application in its configuration page.", + "required": false, + "schema": { + "type": "string" + }, + "example": "admin_readwrite" + } + ], + "responses": { + "200": { + "description": "Does not return any data, but rather should be used in the browser.", + "content": { + "text/html": { + "schema": { + "type": "string", + "format": "html" + } + } + } + }, + "default": { + "description": "Does not return any data, but rather should be used in the browser.", + "content": { + "text/html": { + "schema": { + "type": "string", + "format": "html" + } + } + } + } + }, + "x-box-tag": "authorization", + "security": [], + "servers": [ + { + "url": "https://account.box.com/api/oauth2", + "description": "Server for client-side authentication" + } + ], + "tags": [ + "Authorization" + ] + } + }, + "/oauth2/token": { + "post": { + "operationId": "post_oauth2_token", + "summary": "Request access token", + "description": "Request an Access Token using either a client-side obtained OAuth 2.0\nauthorization code or a server-side JWT assertion.\n\nAn Access Token is a string that enables Box to verify that a\nrequest belongs to an authorized session. In the normal order of\noperations you will begin by requesting authentication from the\n[authorize](#get-authorize) endpoint and Box will send you an\nauthorization code.\n\nYou will then send this code to this endpoint to exchange it for\nan Access Token. The returned Access Token can then be used to to make\nBox API calls.", + "requestBody": { + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "$ref": "#/components/schemas/PostOAuth2Token" + } + } + } + }, + "responses": { + "200": { + "description": "Returns a new Access Token that can be used to make authenticated\nAPI calls by passing along the token in a authorization header as\nfollows `Authorization: Bearer `.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccessToken" + } + } + } + }, + "400": { + "description": "An authentication error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OAuth2Error" + } + } + } + }, + "default": { + "description": "An authentication error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OAuth2Error" + } + } + } + } + }, + "x-box-tag": "authorization", + "security": [], + "servers": [ + { + "url": "https://api.box.com", + "description": "Server for server-side authentication" + } + ], + "tags": [ + "Authorization" + ] + } + }, + "/oauth2/token#refresh": { + "post": { + "operationId": "post_oauth2_token#refresh", + "summary": "Refresh access token", + "description": "Refresh an Access Token using its client ID, secret, and refresh token.", + "requestBody": { + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "$ref": "#/components/schemas/PostOAuth2Token--RefreshAccessToken" + } + } + } + }, + "responses": { + "200": { + "description": "Returns a new Access Token that can be used to make authenticated\nAPI calls by passing along the token in a authorization header as\nfollows `Authorization: Bearer `.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccessToken" + } + } + } + }, + "400": { + "description": "An authentication error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OAuth2Error" + } + } + } + }, + "default": { + "description": "An authentication error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OAuth2Error" + } + } + } + } + }, + "x-box-tag": "authorization", + "security": [], + "servers": [ + { + "url": "https://api.box.com", + "description": "Server for server-side authentication" + } + ], + "tags": [ + "Authorization" + ], + "x-box-is-variation": true + } + }, + "/oauth2/revoke": { + "post": { + "operationId": "post_oauth2_revoke", + "summary": "Revoke access token", + "description": "Revoke an active Access Token, effectively logging a user out\nthat has been previously authenticated.", + "requestBody": { + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "$ref": "#/components/schemas/PostOAuth2Revoke" + } + } + } + }, + "responses": { + "200": { + "description": "Returns an empty response when the token was successfully revoked." + }, + "400": { + "description": "An authentication error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OAuth2Error" + } + } + } + }, + "default": { + "description": "An authentication error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OAuth2Error" + } + } + } + } + }, + "x-box-tag": "authorization", + "security": [], + "servers": [ + { + "url": "https://api.box.com", + "description": "Server for server-side authentication" + } + ], + "tags": [ + "Authorization" + ] + } + }, + "/files/{file_id}": { + "get": { + "operationId": "get_files_id", + "summary": "Get file information", + "description": "Retrieves the details about a file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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`?fields=metadata.enterprise_12345.contractTemplate`.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "if-none-match", + "in": "header", + "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + }, + { + "name": "boxapi", + "in": "header", + "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been\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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "shared_link=[link]&shared_link_password=[password]" + }, + { + "name": "x-rep-hints", + "in": "header", + "description": "A header required to request specific `representations`\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 `64x64` pixel dimensions provide the following\nhints.\n\n`x-rep-hints: [jpg?dimensions=32x32][jpg?dimensions=64x64]`\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]`", + "required": false, + "schema": { + "type": "string", + "nullable": true + }, + "example": "[pdf]" + } + ], + "responses": { + "200": { + "description": "Returns a file object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/File--Full" + } + } + } + }, + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file is not found, or the user does not\nhave access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "415": { + "description": "Returns an error if an action is performed on a file with an\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "files", + "tags": [ + "Files" + ] + }, + "post": { + "operationId": "post_files_id", + "summary": "Restore file", + "description": "Restores a file that has been moved to the trash.\n\nAn optional new parent ID can be provided to restore the file to in case the\noriginal folder has been deleted.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "An optional new name for the file.", + "type": "string", + "example": "Restored.docx" + }, + "parent": { + "allOf": [ + { + "type": "object", + "description": "The parent for this item", + "properties": { + "id": { + "description": "The ID of parent item", + "type": "string", + "example": "123" + } + } + }, + { + "description": "Specifies an optional ID of a folder to restore the file to\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TrashFileRestored" + } + } + } + }, + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if the file is not in the trash.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error if there is an file with the same name\nin the folder the file is being restored to.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "trashed_files", + "tags": [ + "Trashed files" + ] + }, + "put": { + "operationId": "put_files_id", + "summary": "Update file", + "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", + "in": "path", + "description": "The unique identifier that represents 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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "if-match", + "in": "header", + "description": "Ensures this item hasn't recently changed before\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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "An optional different name for the file. This can be used to\nrename the file.", + "type": "string", + "example": "NewFile.txt" + }, + "description": { + "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.", + "type": "string", + "example": "The latest reports. Automatically updated", + "maxLength": 256 + }, + "parent": { + "allOf": [ + { + "type": "object", + "description": "The parent for this item", + "properties": { + "id": { + "description": "The ID of parent item", + "type": "string", + "example": "123" + } + } + }, + { + "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": { + "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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ] + }, + "password": { + "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", + "type": "string", + "example": "do-n8t-use-this-Password", + "nullable": true + }, + "vanity_name": { + "description": "Defines a custom vanity name to use in the shared link URL,\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.", + "type": "string", + "example": "my-shared-link" + }, + "unshared_at": { + "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "permissions": { + "type": "object", + "properties": { + "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", + "type": "boolean", + "example": true + } + } + } + } + }, + { + "description": "Defines a shared link for a file. Set this to `null` to remove\nthe shared link." + } + ], + "nullable": true + }, + "lock": { + "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.", + "type": "object", + "nullable": true, + "properties": { + "access": { + "description": "The type of this object.", + "type": "string", + "example": "lock", + "enum": [ + "lock" + ] + }, + "expires_at": { + "description": "Defines the time at which the lock expires.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "is_download_prevented": { + "description": "Defines if the file can be downloaded while it is locked.", + "type": "boolean", + "example": true + } + }, + "required": [ + "type" + ] + }, + "disposition_at": { + "description": "The retention expiration timestamp for the given file. This\ndate cannot be shortened once set on a file.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "permissions": { + "description": "Defines who can download a file.", + "type": "object", + "properties": { + "can_download": { + "description": "Defines who is allowed to download this file. The possible\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", + "example": "open", + "enum": [ + "open", + "company" + ] + } + } + }, + "collections": { + "description": "An array of collections to make this file\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 file from all collections.\n\n[1]: e://get-collections", + "type": "array", + "items": { + "title": "Reference", + "description": "The bare basic reference for an object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this object", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type for this object", + "type": "string", + "example": "file" + } + } + }, + "nullable": true + }, + "tags": { + "description": "The tags for this item. These tags are shown in\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.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "approved" + ], + "maxItems": 100, + "minItems": 1 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns a file object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/File--Full" + } + } + } + }, + "400": { + "description": "Returned when the new retention time > maximum retention length.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned if the user does not have all the permissions to complete the\nupdate.\n\n* `access_denied_insufficient_permissions` returned\nwhen the authenticated user does not have access\nto the destination folder to move the file to.\n* Returned when retention time is shorter or equal to current retention\ntimestamp.\n* Returned when a `file_id` that is not under retention is entered.\n* Returned when a file that is retained but the disposition action is set\nto `remove_retention`\n* `forbidden_by_policy` is returned if copying a folder is\nforbidden due to information barrier restrictions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file is not found, or the user does not\nhave access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "412": { + "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "files", + "tags": [ + "Files" + ] + }, + "delete": { + "operationId": "delete_files_id", + "summary": "Delete file", + "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", + "in": "path", + "description": "The unique identifier that represents 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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "if-match", + "in": "header", + "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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + } + ], + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file is not found or has already been deleted, or the user\ndoes not have access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "412": { + "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "files", + "tags": [ + "Files" + ] + } + }, + "/files/{file_id}/app_item_associations": { + "get": { + "operationId": "get_files_id_app_item_associations", + "summary": "List file app item associations", + "description": "**This is a beta feature, which means that its availability might be limited.**\nReturns all app items the file is associated with. This includes app items\nassociated with ancestors of the file. Assuming the context user has access\nto the file, the type/ids are revealed even if the context user does not\nhave **View** permission on the app item.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "application_type", + "in": "query", + "description": "If given, only return app items for this application type", + "required": false, + "schema": { + "type": "string", + "nullable": false + }, + "example": "hubs" + } + ], + "responses": { + "200": { + "description": "Returns a collection of app item objects. If there are no\napp items on this file, an empty collection will be returned.\nThis list includes app items on ancestors of this File.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppItemAssociations" + } + } + } + }, + "404": { + "description": "Returned if the file is not found, or the user does not\nhave access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "app_item_associations", + "tags": [ + "App item associations" + ] + } + }, + "/files/{file_id}/content": { + "get": { + "operationId": "get_files_id_content", + "summary": "Download file", + "description": "Returns the contents of a file in binary format.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "range", + "in": "header", + "description": "The byte range of the content to download.\n\nThe format `bytes={start_byte}-{end_byte}` can be used to specify\nwhat section of the file to download.", + "required": false, + "schema": { + "type": "string" + }, + "example": "bytes=0-1024" + }, + { + "name": "boxapi", + "in": "header", + "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been\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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "shared_link=[link]&shared_link_password=[password]" + }, + { + "name": "version", + "in": "query", + "description": "The file version to download", + "required": false, + "schema": { + "type": "string" + }, + "example": "4" + }, + { + "name": "access_token", + "in": "query", + "description": "An optional access token that can be used to pre-authenticate this request, which means that a download link can be shared with a browser or a third party service without them needing to know how to handle the authentication.\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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + } + ], + "responses": { + "200": { + "description": "Returns the requested file if the client has the **follow\nredirects** setting enabled to automatically\nfollow HTTP `3xx` responses as redirects. If not, the request\nwill return `302` instead.\nFor details, see\nthe [download file guide](g://downloads/file#download-url).", + "content": { + "application/octet-stream": { + "schema": { + "description": "The binary content of the file", + "type": "string", + "format": "binary" + } + } + } + }, + "202": { + "description": "If the file is not ready to be downloaded yet `Retry-After` header will\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", + "schema": { + "type": "integer" + } + } + } + }, + "302": { + "description": "If the file is available for download 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 to actually download the file.", + "headers": { + "Location": { + "description": "A pointer to the download URL", + "schema": { + "type": "string", + "format": "url" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "downloads", + "tags": [ + "Downloads" + ] + }, + "post": { + "operationId": "post_files_id_content", + "summary": "Upload file version", + "description": "Update a file's content. For file sizes over 50MB we recommend\nusing the Chunk Upload APIs.\n\nThe `attributes` part of the body must come **before** the\n`file` part. Requests that do not follow this format when\nuploading the file will receive a HTTP `400` error with a\n`metadata_after_file_contents` error code.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "if-match", + "in": "header", + "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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "content-md5", + "in": "header", + "description": "An optional header containing the SHA1 hash of the file to\nensure that the file was not corrupted in transit.", + "required": false, + "schema": { + "type": "string" + }, + "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc" + } + ], + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "attributes": { + "description": "The additional attributes of the file being uploaded. Mainly the\nname and the parent folder. These attributes are part of the multi\npart request body and are in JSON format.\n\n\n\n The `attributes` part of the body must come **before** the\n `file` part. Requests that do not follow this format when\n uploading the file will receive a HTTP `400` error with a\n `metadata_after_file_contents` error code.\n\n", + "type": "object", + "properties": { + "name": { + "description": "An optional new name for the file. If specified, the file\nwill be renamed when the new version is uploaded.", + "type": "string", + "example": "Photo 2.0.png" + }, + "content_modified_at": { + "description": "Defines the time the file was last modified at.\n\nIf not set, the upload time will be used.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + }, + "required": [ + "name" + ] + }, + "file": { + "description": "The content of the file to upload to Box.\n\n\n\n The `attributes` part of the body must come **before** the\n `file` part. Requests that do not follow this format when\n uploading the file will receive a HTTP `400` error with a\n `metadata_after_file_contents` error code.\n\n", + "type": "string", + "format": "binary" + } + }, + "required": [ + "attributes", + "file" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns the new file object in a list.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Files" + } + } + } + }, + "412": { + "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "uploads", + "servers": [ + { + "url": "https://upload.box.com/api/2.0", + "description": "Server for file uploads" + } + ], + "tags": [ + "Uploads" + ] + } + }, + "/files/content": { + "options": { + "operationId": "options_files_content", + "summary": "Preflight check before upload", + "tags": [ + "Files" + ], + "x-box-tag": "uploads", + "description": "Performs a check to verify that a file will be accepted by Box\nbefore you upload the entire file.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "The name for the file", + "type": "string", + "example": "File.mp4" + }, + "size": { + "description": "The size of the file in bytes", + "type": "integer", + "format": "int32", + "example": 1024 + }, + "parent": { + "allOf": [ + { + "type": "object", + "description": "The parent for this item", + "properties": { + "id": { + "description": "The ID of parent item", + "type": "string", + "example": "123" + } + } + }, + { + "description": "The parent folder to upload the file to" + } + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "If the check passed, the response will include a session URL that\ncan be used to upload the file to.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UploadUrl" + } + } + } + }, + "409": { + "description": "If the check did not pass, the response will include some details on\nwhy it did not pass.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + } + }, + "post": { + "operationId": "post_files_content", + "summary": "Upload file", + "description": "Uploads a small file to Box. For file sizes over 50MB we recommend\nusing the Chunk Upload APIs.\n\nThe `attributes` part of the body must come **before** the\n`file` part. Requests that do not follow this format when\nuploading the file will receive a HTTP `400` error with a\n`metadata_after_file_contents` error code.", + "parameters": [ + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "content-md5", + "in": "header", + "description": "An optional header containing the SHA1 hash of the file to\nensure that the file was not corrupted in transit.", + "required": false, + "schema": { + "type": "string" + }, + "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc" + } + ], + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "attributes": { + "description": "The additional attributes of the file being uploaded. Mainly the\nname and the parent folder. These attributes are part of the multi\npart request body and are in JSON format.\n\n\n\n The `attributes` part of the body must come **before** the\n `file` part. Requests that do not follow this format when\n uploading the file will receive a HTTP `400` error with a\n `metadata_after_file_contents` error code.\n\n", + "type": "object", + "properties": { + "name": { + "description": "The name of the file", + "type": "string", + "example": "Photo.png" + }, + "parent": { + "description": "The parent folder to upload the file to", + "type": "object", + "properties": { + "id": { + "description": "The id of the parent folder. Use\n`0` for the user's root folder.", + "type": "string", + "example": "124132" + } + }, + "required": [ + "id" + ] + }, + "content_created_at": { + "description": "Defines the time the file was originally created at.\n\nIf not set, the upload time will be used.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "content_modified_at": { + "description": "Defines the time the file was last modified at.\n\nIf not set, the upload time will be used.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + }, + "required": [ + "name", + "parent" + ] + }, + "file": { + "description": "The content of the file to upload to Box.\n\n\n\n The `attributes` part of the body must come **before** the\n `file` part. Requests that do not follow this format when\n uploading the file will receive a HTTP `400` error with a\n `metadata_after_file_contents` error code.\n\n", + "type": "string", + "format": "binary" + } + }, + "required": [ + "attributes", + "file" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns the new file object in a list.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Files" + } + } + } + }, + "400": { + "description": "Returns an error if some of the parameters are missing or\nnot valid.\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if the parent folder\ndoes not exist or if the user\nis not authorized to access the parent folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error if the file already exists,\nor the account has run out of disk space.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "uploads", + "servers": [ + { + "url": "https://upload.box.com/api/2.0", + "description": "Server for file uploads" + } + ], + "tags": [ + "Uploads" + ] + } + }, + "/files/upload_sessions": { + "post": { + "operationId": "post_files_upload_sessions", + "summary": "Create upload session", + "description": "Creates an upload session for a new file.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "folder_id": { + "description": "The ID of the folder to upload the new file to.", + "type": "string", + "example": "0" + }, + "file_size": { + "description": "The total number of bytes of the file to be uploaded", + "type": "integer", + "format": "int64", + "example": 104857600 + }, + "file_name": { + "description": "The name of new file", + "type": "string", + "example": "Project.mov" + } + }, + "required": [ + "folder_id", + "file_size", + "file_name" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new upload session.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UploadSession" + } + } + } + }, + "400": { + "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `missing_destination`: No `folder_id` was provided\n* `invalid_folder_id`: `folder_id` is not valid\n* `item_name_invalid`: `file_name` is not valid\n* `missing_file_size`: `file_size` was not provided\n* `invalid_file_size`: `file_size` was not a valid number\n* `file_size_too_small`: `file_size` is below minimum file size for\n uploads via this API\n* `missing_file_name`: `file_name` was not provided", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error if the operation is not allowed for some reason.\n\n* `storage_limit_exceeded`: Account storage limit reached", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if the parent folder could not be found, or\nthe authenticated user does not have access to it.\n\n* `invalid_parameter`: The `folder_id` value represents a\n folder that the user does not have access to, or does not\n exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error if the file already exists,\nor the account has run out of disk space.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "chunked_uploads", + "servers": [ + { + "url": "https://upload.box.com/api/2.0", + "description": "Server for file uploads" + } + ], + "tags": [ + "Uploads (Chunked)" + ] + } + }, + "/files/{file_id}/upload_sessions": { + "post": { + "operationId": "post_files_id_upload_sessions", + "summary": "Create upload session for existing file", + "description": "Creates an upload session for an existing file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "file_size": { + "description": "The total number of bytes of the file to be uploaded", + "type": "integer", + "format": "int64", + "example": 104857600 + }, + "file_name": { + "description": "The optional new name of new file", + "type": "string", + "example": "Project.mov" + } + }, + "required": [ + "file_size" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new upload session.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UploadSession" + } + } + } + }, + "409": { + "description": "Returns an error if the file already exists,\nor if the account has run out of disk space.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "chunked_uploads", + "servers": [ + { + "url": "https://upload.box.com/api/2.0", + "description": "Server for file uploads" + } + ], + "tags": [ + "Uploads (Chunked)" + ] + } + }, + "/files/upload_sessions/{upload_session_id}": { + "get": { + "operationId": "get_files_upload_sessions_id", + "summary": "Get upload session", + "description": "Return information about an upload session.\n\nThe actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) endpoint.", + "parameters": [ + { + "name": "upload_session_id", + "in": "path", + "description": "The ID of the upload session.", + "required": true, + "schema": { + "type": "string" + }, + "example": "D5E3F7A" + } + ], + "responses": { + "200": { + "description": "Returns an upload session object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UploadSession" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "chunked_uploads", + "servers": [ + { + "url": "https://{box-upload-server}/api/2.0", + "description": "Server for file uploads", + "variables": { + "box-upload-server": { + "description": "The server for the upload session.", + "default": "upload.box.com" + } + } + } + ], + "tags": [ + "Uploads (Chunked)" + ], + "x-box-enable-explorer": false + }, + "put": { + "operationId": "put_files_upload_sessions_id", + "summary": "Upload part of file", + "description": "Uploads a chunk of a file for an upload session.\n\nThe actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions)\nand [`Get upload session`](e://get-files-upload-sessions-id) endpoints.", + "parameters": [ + { + "name": "upload_session_id", + "in": "path", + "description": "The ID of the upload session.", + "required": true, + "schema": { + "type": "string" + }, + "example": "D5E3F7A" + }, + { + "name": "digest", + "in": "header", + "description": "The [RFC3230][1] message digest of the chunk uploaded.\n\nOnly SHA1 is supported. The SHA1 digest must be base64\nencoded. The format of this header is as\n`sha=BASE64_ENCODED_DIGEST`.\n\nTo get the value for the `SHA` digest, use the\nopenSSL command to encode the file part:\n`openssl sha1 -binary | base64`\n\n[1]: https://tools.ietf.org/html/rfc3230", + "required": true, + "schema": { + "type": "string" + }, + "example": "sha=fpRyg5eVQletdZqEKaFlqwBXJzM=" + }, + { + "name": "content-range", + "in": "header", + "description": "The byte range of the chunk.\n\nMust not overlap with the range of a part already\nuploaded this session. Each part’s size must be\nexactly equal in size to the part size specified\nin the upload session that you created.\nOne exception is the last part of the file, as this can be smaller.\n\nWhen providing the value for `content-range`, remember that:\n\n* The lower bound of each part's byte range\n must be a multiple of the part size.\n* The higher bound must be a multiple of the part size - 1.", + "required": true, + "schema": { + "type": "string" + }, + "example": "bytes 8388608-16777215/445856194" + } + ], + "requestBody": { + "content": { + "application/octet-stream": { + "schema": { + "description": "The binary content of the file", + "type": "string", + "format": "binary" + } + } + } + }, + "responses": { + "200": { + "description": "Chunk has been uploaded successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UploadedPart" + } + } + } + }, + "409": { + "description": "Returns an error if the chunk conflicts with another\nchunk previously uploaded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "412": { + "description": "Returns an error if a precondition was not met.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "416": { + "description": "Returns an error if the content range does not match a specified range\nfor the session.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "chunked_uploads", + "servers": [ + { + "url": "https://{box-upload-server}/api/2.0", + "description": "Server for file uploads", + "variables": { + "box-upload-server": { + "description": "The server for the upload session.", + "default": "upload.box.com" + } + } + } + ], + "tags": [ + "Uploads (Chunked)" + ], + "x-box-enable-explorer": false + }, + "delete": { + "operationId": "delete_files_upload_sessions_id", + "summary": "Remove upload session", + "description": "Abort an upload session and discard all data uploaded.\n\nThis cannot be reversed.\n\nThe actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions)\nand [`Get upload session`](e://get-files-upload-sessions-id) endpoints.", + "parameters": [ + { + "name": "upload_session_id", + "in": "path", + "description": "The ID of the upload session.", + "required": true, + "schema": { + "type": "string" + }, + "example": "D5E3F7A" + } + ], + "responses": { + "204": { + "description": "A blank response is returned if the session was\nsuccessfully aborted." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "chunked_uploads", + "servers": [ + { + "url": "https://{box-upload-server}/api/2.0", + "description": "Server for file uploads", + "variables": { + "box-upload-server": { + "description": "The server for the upload session.", + "default": "upload.box.com" + } + } + } + ], + "tags": [ + "Uploads (Chunked)" + ], + "x-box-enable-explorer": false + } + }, + "/files/upload_sessions/{upload_session_id}/parts": { + "get": { + "operationId": "get_files_upload_sessions_id_parts", + "summary": "List parts", + "description": "Return a list of the chunks uploaded to the upload session so far.\n\nThe actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions)\nand [`Get upload session`](e://get-files-upload-sessions-id) endpoints.", + "parameters": [ + { + "name": "upload_session_id", + "in": "path", + "description": "The ID of the upload session.", + "required": true, + "schema": { + "type": "string" + }, + "example": "D5E3F7A" + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a list of parts that have been uploaded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UploadParts" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "chunked_uploads", + "servers": [ + { + "url": "https://{box-upload-server}/api/2.0", + "description": "Server for file uploads", + "variables": { + "box-upload-server": { + "description": "The server for the upload session.", + "default": "upload.box.com" + } + } + } + ], + "tags": [ + "Uploads (Chunked)" + ], + "x-box-enable-explorer": false + } + }, + "/files/upload_sessions/{upload_session_id}/commit": { + "post": { + "operationId": "post_files_upload_sessions_id_commit", + "summary": "Commit upload session", + "description": "Close an upload session and create a file from the uploaded chunks.\n\nThe actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions)\nand [`Get upload session`](e://get-files-upload-sessions-id) endpoints.", + "parameters": [ + { + "name": "upload_session_id", + "in": "path", + "description": "The ID of the upload session.", + "required": true, + "schema": { + "type": "string" + }, + "example": "D5E3F7A" + }, + { + "name": "digest", + "in": "header", + "description": "The [RFC3230][1] message digest of the whole file.\n\nOnly SHA1 is supported. The SHA1 digest must be Base64\nencoded. The format of this header is as\n`sha=BASE64_ENCODED_DIGEST`.\n\n[1]: https://tools.ietf.org/html/rfc3230", + "required": true, + "schema": { + "type": "string" + }, + "example": "sha=fpRyg5eVQletdZqEKaFlqwBXJzM=" + }, + { + "name": "if-match", + "in": "header", + "description": "Ensures this item hasn't recently changed before\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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + }, + { + "name": "if-none-match", + "in": "header", + "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "parts": { + "description": "The list details for the uploaded parts", + "type": "array", + "items": { + "$ref": "#/components/schemas/UploadPart" + } + } + }, + "required": [ + "parts" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns the file object in a list.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Files" + } + } + } + }, + "202": { + "description": "Returns when all chunks have been uploaded but not yet processed.\n\nInspect the upload session to get more information about the\nprogress of processing the chunks, then retry committing the file\nwhen all chunks have processed.", + "headers": { + "Retry-After": { + "description": "Indicates the number of seconds the client should wait before\nattempting their commit request again.", + "schema": { + "type": "integer" + } + } + } + }, + "409": { + "description": "Returns an error if there is already a file with the same name\nin the target folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "412": { + "description": "Returns an error if the `If-Match` or `If-None-Match` conditions fail.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "chunked_uploads", + "servers": [ + { + "url": "https://{box-upload-server}/api/2.0", + "description": "Server for file uploads", + "variables": { + "box-upload-server": { + "description": "The server for the upload session.", + "default": "upload.box.com" + } + } + } + ], + "tags": [ + "Uploads (Chunked)" + ], + "x-box-enable-explorer": false + } + }, + "/files/{file_id}/copy": { + "post": { + "operationId": "post_files_id_copy", + "summary": "Copy file", + "description": "Creates a copy of a file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "An optional new name for the copied file.\n\nThere are some restrictions to the file name. Names containing\nnon-printable ASCII characters, forward and backward slashes\n(`/`, `\\`), and protected names like `.` and `..` are\nautomatically sanitized by removing the non-allowed\ncharacters.", + "type": "string", + "example": "FileCopy.txt", + "maxLength": 255 + }, + "version": { + "description": "An optional ID of the specific file version to copy.", + "type": "string", + "example": "0" + }, + "parent": { + "description": "The destination folder to copy the file to.", + "type": "object", + "properties": { + "id": { + "description": "The ID of folder to copy the file to.", + "type": "string", + "example": "0" + } + }, + "required": [ + "id" + ] + } + }, + "nullable": false, + "required": [ + "parent" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new file object representing the copied file.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/File--Full" + } + } + } + }, + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error when the user does not have the\nright permissions to create the copy a file.\n\n* `forbidden_by_policy`: Returned if copying a file is\nforbidden due to information barrier restrictions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if either the source file or the destination\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", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "files", + "tags": [ + "Files" + ] + } + }, + "/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`, `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", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents 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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "extension", + "in": "path", + "description": "The file format for the thumbnail", + "required": true, + "schema": { + "type": "string", + "enum": [ + "png", + "jpg" + ] + }, + "example": "png" + }, + { + "name": "min_height", + "in": "query", + "description": "The minimum height of the thumbnail", + "schema": { + "type": "integer", + "maximum": 320, + "minimum": 32 + }, + "example": 32 + }, + { + "name": "min_width", + "in": "query", + "description": "The minimum width of the thumbnail", + "schema": { + "type": "integer", + "maximum": 320, + "minimum": 32 + }, + "example": 32 + }, + { + "name": "max_height", + "in": "query", + "description": "The maximum height of the thumbnail", + "required": false, + "schema": { + "type": "integer", + "maximum": 320, + "minimum": 32 + }, + "example": 320 + }, + { + "name": "max_width", + "in": "query", + "description": "The maximum width of the thumbnail", + "required": false, + "schema": { + "type": "integer", + "maximum": 320, + "minimum": 32 + }, + "example": 320 + } + ], + "responses": { + "200": { + "description": "When a thumbnail can be created the thumbnail data will be\nreturned in the body of the response.", + "content": { + "image/jpg": { + "schema": { + "description": "The thumbnail", + "type": "string", + "format": "binary" + } + }, + "image/png": { + "schema": { + "description": "The thumbnail", + "type": "string", + "format": "binary" + } + } + } + }, + "202": { + "description": "Sometimes generating a thumbnail can take a few seconds. In these\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.", + "schema": { + "type": "integer", + "format": "int64" + } + }, + "Location": { + "description": "A pointer to a placeholder graphic that can be used until the\nthumbnail has been generated.", + "schema": { + "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.", + "schema": { + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file is not found, or the user does not\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", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "files", + "tags": [ + "Files" + ] + } + }, + "/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.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents 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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + } + ], + "responses": { + "200": { + "description": "Returns a collection of collaboration objects. If there are no\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Collaborations" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "list_collaborations", + "tags": [ + "Collaborations (List)" + ] + } + }, + "/files/{file_id}/comments": { + "get": { + "operationId": "get_files_id_comments", + "summary": "List file comments", + "description": "Retrieves a list of comments for a file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a collection of comment objects. If there are no\ncomments on this file an empty collection will be returned.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Comments" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "comments", + "tags": [ + "Comments" + ] + } + }, + "/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.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents 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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "200": { + "description": "Returns a list of tasks on a file.\n\nIf there are no tasks on this file an empty collection is returned\ninstead.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Tasks" + } + } + } + }, + "404": { + "description": "Returns an error when the file could not be found or the user does not\nhave access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returns an error when the `file_id` was not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "500": { + "description": "Returns an error when an attempt was made to retrieve tasks for the file\nwith ID `0`.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "tasks", + "tags": [ + "Tasks" + ] + } + }, + "/files/{file_id}/trash": { + "get": { + "operationId": "get_files_id_trash", + "summary": "Get trashed file", + "description": "Retrieves a file that has been moved to the trash.\n\nPlease note that only if the file itself has been moved to the\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", + "in": "path", + "description": "The unique identifier that represents 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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns the file that was trashed,\nincluding information about when the it\nwas moved to the trash.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TrashFile" + } + } + } + }, + "404": { + "description": "Returns an error if the file can not be found directly\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "trashed_files", + "tags": [ + "Trashed files" + ] + }, + "delete": { + "operationId": "delete_files_id_trash", + "summary": "Permanently remove file", + "description": "Permanently deletes a file that is in the trash.\nThis action cannot be undone.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "trashed_files", + "tags": [ + "Trashed files" + ] + } + }, + "/files/{file_id}/versions": { + "get": { + "operationId": "get_files_id_versions", + "summary": "List all file versions", + "description": "Retrieve a list of the past versions for a file.\n\nVersions are only tracked by Box users with premium accounts. To fetch the ID\nof the current version of a file, use the `GET /file/:id` API.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns an array of past versions for this file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileVersions" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_versions", + "tags": [ + "File versions" + ] + } + }, + "/files/{file_id}/versions/{file_version_id}": { + "get": { + "operationId": "get_files_id_versions_id", + "summary": "Get file version", + "description": "Retrieve a specific version of a file.\n\nVersions are only tracked for Box users with premium accounts.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "file_version_id", + "in": "path", + "description": "The ID of the file version", + "required": true, + "schema": { + "type": "string" + }, + "example": "1234" + } + ], + "responses": { + "200": { + "description": "Returns a specific version of a file.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileVersion--Full" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_versions", + "tags": [ + "File versions" + ] + }, + "delete": { + "operationId": "delete_files_id_versions_id", + "summary": "Remove file version", + "description": "Move a file version to the trash.\n\nVersions are only tracked for Box users with premium accounts.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "file_version_id", + "in": "path", + "description": "The ID of the file version", + "required": true, + "schema": { + "type": "string" + }, + "example": "1234" + }, + { + "name": "if-match", + "in": "header", + "description": "Ensures this item hasn't recently changed before\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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the file has been successfully\ndeleted." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_versions", + "tags": [ + "File versions" + ] + }, + "put": { + "operationId": "put_files_id_versions_id", + "summary": "Restore file version", + "description": "Restores a specific version of a file after it was deleted.\nDon't use this endpoint to restore Box Notes,\nas it works with file formats such as PDF, DOC,\nPPTX or similar.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "file_version_id", + "in": "path", + "description": "The ID of the file version", + "required": true, + "schema": { + "type": "string" + }, + "example": "1234" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "The file version to be\nrestored", + "type": "object", + "properties": { + "trashed_at": { + "description": "Set this to `null` to clear\nthe date and restore the file.", + "type": "string", + "example": null, + "nullable": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns a restored file version object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileVersion--Full" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_versions", + "tags": [ + "File versions" + ] + } + }, + "/files/{file_id}/versions/current": { + "post": { + "operationId": "post_files_id_versions_current", + "summary": "Promote file version", + "description": "Promote a specific version of a file.\n\nIf previous versions exist, this method can be used to\npromote one of the older versions to the top of the version history.\n\nThis creates a new copy of the old version and puts it at the\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.\n\nDon't use this endpoint to restore Box Notes,\nas it works with file formats such as PDF, DOC,\nPPTX or similar.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "The file version to promote", + "type": "object", + "properties": { + "id": { + "description": "The file version ID", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type to promote", + "type": "string", + "example": "file_version", + "enum": [ + "file_version" + ] + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Returns a newly created file version object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileVersion--Full" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_versions", + "tags": [ + "File versions" + ] + } + }, + "/files/{file_id}/metadata": { + "get": { + "operationId": "get_files_id_metadata", + "summary": "List metadata instances on file", + "description": "Retrieves all metadata for a given file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "200": { + "description": "Returns all the metadata associated with a file.\n\nThis API does not support pagination and will therefore always return\nall of the metadata associated to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Metadatas" + } + } + } + }, + "403": { + "description": "Returned when the request parameters are not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned when the user does not have access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_metadata", + "tags": [ + "Metadata instances (Files)" + ] + } + }, + "/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo": { + "get": { + "operationId": "get_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", + "summary": "Get classification on file", + "description": "Retrieves the classification metadata instance that\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", + "in": "path", + "description": "The unique identifier that represents 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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Classification" + } + } + } + }, + "403": { + "description": "Returned when the request parameters are not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the metadata template specified\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned when the method was not allowed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_classifications", + "tags": [ + "Classifications on files" + ] + }, + "post": { + "operationId": "post_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", + "summary": "Add classification to file", + "description": "Adds a classification to a file by specifying the label of the\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", + "in": "path", + "description": "The unique identifier that represents 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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "Box__Security__Classification__Key": { + "description": "The name of the classification to apply to this file.\n\nTo list the available classifications in an enterprise,\nuse the classification API to retrieve the\n[classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)\nwhich lists all available classification keys.", + "type": "string", + "example": "Sensitive" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Returns the classification template instance\nthat was applied to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Classification" + } + } + } + }, + "400": { + "description": "Returns an error when the request body is not valid.\n\n* `schema_validation_failed` - The request body contains a value for\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the file or metadata template was not found.\n\n* `not_found` - The file could not be found, or the user does not have\naccess to the file.\n* `instance_tuple_not_found` - The metadata template was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error when an instance of this metadata template is already\npresent on the file.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_classifications", + "tags": [ + "Classifications on files" + ] + }, + "put": { + "operationId": "put_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", + "summary": "Update classification on file", + "description": "Updates a classification on a file.\n\nThe classification can only be updated if a classification has already been\napplied to the file before. When editing classifications, only values are\ndefined for the enterprise will be accepted.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "application/json-patch+json": { + "schema": { + "description": "A list containing the one change to make, to\nupdate the classification label.", + "type": "array", + "items": { + "type": "object", + "description": "The operation to perform on the classification\nmetadata template instance. In this case, it use\nused to replace the value stored for the\n`Box__Security__Classification__Key` field with a new\nvalue.", + "required": [ + "op", + "path", + "value" + ], + "properties": { + "op": { + "description": "`replace`", + "type": "string", + "example": "replace", + "enum": [ + "replace" + ] + }, + "path": { + "description": "Defines classifications \navailable in the enterprise.", + "type": "string", + "example": "/Box__Security__Classification__Key", + "enum": [ + "/Box__Security__Classification__Key" + ] + }, + "value": { + "description": "The name of the classification to apply to this file.\n\nTo list the available classifications in an enterprise,\nuse the classification API to retrieve the\n[classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)\nwhich lists all available classification keys.", + "type": "string", + "example": "Sensitive" + } + } + }, + "required": [ + "items" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated classification metadata template instance.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Classification" + } + } + } + }, + "400": { + "description": "Returns an error when the request body is not valid.\n\n* `bad_request` - The request body format is not an array of valid JSON\nPatch operations.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "500": { + "description": "Returns an error in some edge cases when the request body is not a valid\narray of JSON Patch items.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_classifications", + "tags": [ + "Classifications on files" + ] + }, + "delete": { + "operationId": "delete_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", + "summary": "Remove classification from file", + "description": "Removes any classifications from a file.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the classification is\nsuccessfully deleted." + }, + "400": { + "description": "Returned when the request parameters are not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the file does not have any classification applied\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned when the method was not allowed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_classifications", + "tags": [ + "Classifications on files" + ] + } + }, + "/files/{file_id}/metadata/{scope}/{template_key}": { + "get": { + "operationId": "get_files_id_metadata_id_id", + "summary": "Get metadata instance on file", + "description": "Retrieves the instance of a metadata template that has been applied to a\nfile.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents 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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "scope", + "in": "path", + "description": "The scope of the metadata template", + "required": true, + "schema": { + "type": "string", + "enum": [ + "global", + "enterprise" + ] + }, + "example": "global" + }, + { + "name": "template_key", + "in": "path", + "description": "The name of the metadata template", + "required": true, + "schema": { + "type": "string" + }, + "example": "properties" + } + ], + "responses": { + "201": { + "description": "An instance of the metadata template that includes\nadditional \"key:value\" pairs defined by the user or\nan application.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Metadata--Full" + } + } + } + }, + "403": { + "description": "Returned when the request parameters are not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the metadata template specified\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned when the method was not allowed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_metadata", + "tags": [ + "Metadata instances (Files)" + ] + }, + "post": { + "operationId": "post_files_id_metadata_id_id", + "summary": "Create metadata instance on file", + "description": "Applies an instance of a metadata template to a file.\n\nIn most cases only values that are present in the metadata template\nwill be accepted, except for the `global.properties` template which accepts\nany key-value pair.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "scope", + "in": "path", + "description": "The scope of the metadata template", + "required": true, + "schema": { + "type": "string", + "enum": [ + "global", + "enterprise" + ] + }, + "example": "global" + }, + { + "name": "template_key", + "in": "path", + "description": "The name of the metadata template", + "required": true, + "schema": { + "type": "string" + }, + "example": "properties" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "example": { + "name": "Aaron Levie" + }, + "additionalProperties": { + "allOf": [ + {}, + { + "example": "Aaron Levie" + }, + { + "description": "A value for each of the fields that are present\non the metadata template.\nFor the `global.properties` template this can be\na list of zero or more fields,\nas this template allows for any generic key-value pairs \nto be stored stored in 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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Metadata--Full" + } + } + } + }, + "400": { + "description": "Returns an error when the request body is not valid.\n\n* `schema_validation_failed` - The request body contains a value for\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the file or metadata template was not found.\n\n* `not_found` - The file could not be found, or the user does not have\naccess to the file.\n* `instance_tuple_not_found` - The metadata template was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error when an instance of this metadata template is already\npresent on the file.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_metadata", + "tags": [ + "Metadata instances (Files)" + ], + "x-box-enable-explorer": false + }, + "put": { + "operationId": "put_files_id_metadata_id_id", + "summary": "Update metadata instance on file", + "description": "Updates a piece of metadata on a file.\n\nThe metadata instance can only be updated if the template has already been\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", + "in": "path", + "description": "The unique identifier that represents 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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "scope", + "in": "path", + "description": "The scope of the metadata template", + "required": true, + "schema": { + "type": "string", + "enum": [ + "global", + "enterprise" + ] + }, + "example": "global" + }, + { + "name": "template_key", + "in": "path", + "description": "The name of the metadata template", + "required": true, + "schema": { + "type": "string" + }, + "example": "properties" + } + ], + "requestBody": { + "content": { + "application/json-patch+json": { + "schema": { + "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902)\nspecification for the changes to make to the metadata\ninstance.\n\nThe changes are represented as a JSON array of\noperation objects.", + "type": "array", + "items": { + "title": "A metadata instance update operation", + "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a\nchange to make to the metadata instance.", + "type": "object", + "properties": { + "op": { + "description": "The type of change to perform on the template. Some\nof these are hazardous as they will change existing templates.", + "type": "string", + "example": "add", + "enum": [ + "add", + "replace", + "remove", + "test", + "move", + "copy" + ] + }, + "path": { + "description": "The location in the metadata JSON object\nto apply the changes to, in the format of a\n[JSON-Pointer](https://tools.ietf.org/html/rfc6901).\n\nThe path must always be prefixed with a `/` to represent the root\nof the template. The characters `~` and `/` are reserved\ncharacters and must be escaped in the key.", + "type": "string", + "example": "/currentState" + }, + "value": { + "description": "The value to be set or tested.\n\nRequired for `add`, `replace`, and `test` operations. For `add`,\nif the value exists already the previous value will be overwritten\nby the new value. For `replace`, the value must exist before\nreplacing.\n\nFor `test`, the existing value at the `path` location must match\nthe specified value.", + "type": "string", + "example": "reviewed" + }, + "from": { + "description": "The location in the metadata JSON object to move or copy a value\nfrom. Required for `move` or `copy` operations and must be in the\nformat of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901).", + "type": "string", + "example": "/nextState" + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated metadata template instance, with the\ncustom template data included.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Metadata--Full" + } + } + } + }, + "400": { + "description": "Returns an error when the request body is not valid.\n\n* `bad_request` - The request body format is not an array of valid JSON\nPatch objects.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "500": { + "description": "Returns an error in some edge cases when the request body is not a valid\narray of JSON Patch items.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_metadata", + "tags": [ + "Metadata instances (Files)" + ] + }, + "delete": { + "operationId": "delete_files_id_metadata_id_id", + "summary": "Remove metadata instance from file", + "description": "Deletes a piece of file metadata.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "scope", + "in": "path", + "description": "The scope of the metadata template", + "required": true, + "schema": { + "type": "string", + "enum": [ + "global", + "enterprise" + ] + }, + "example": "global" + }, + { + "name": "template_key", + "in": "path", + "description": "The name of the metadata template", + "required": true, + "schema": { + "type": "string" + }, + "example": "properties" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the metadata is\nsuccessfully deleted." + }, + "400": { + "description": "Returned when the request parameters are not valid. This may happen of the\n`scope` is not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the file does not have an instance of the metadata\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned when the method was not allowed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_metadata", + "tags": [ + "Metadata instances (Files)" + ] + } + }, + "/files/{file_id}/metadata/global/boxSkillsCards": { + "get": { + "operationId": "get_files_id_metadata_global_boxSkillsCards", + "summary": "List Box Skill cards on file", + "description": "List the Box Skills metadata cards that are attached to a file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "200": { + "description": "Returns all the metadata associated with a file.\n\nThis API does not support pagination and will therefore always return\nall of the metadata associated to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SkillCardsMetadata" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "skills", + "tags": [ + "Skills" + ] + }, + "post": { + "operationId": "post_files_id_metadata_global_boxSkillsCards", + "summary": "Create Box Skill cards on file", + "description": "Applies one or more Box Skills metadata cards to a file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "cards": { + "description": "A list of Box Skill cards to apply to this file.", + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/KeywordSkillCard" + }, + { + "$ref": "#/components/schemas/TimelineSkillCard" + }, + { + "$ref": "#/components/schemas/TranscriptSkillCard" + }, + { + "$ref": "#/components/schemas/StatusSkillCard" + } + ] + } + } + }, + "required": [ + "cards" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns the instance of the template that was applied to the file,\nincluding the data that was applied to the template.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SkillCardsMetadata" + } + } + } + }, + "400": { + "description": "Returns an error when the request body is not valid.\n\n* `schema_validation_failed` - The request body contains a value for\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the file or metadata template was not found.\n\n* `not_found` - The file could not be found, or the user does not have\naccess to the file.\n* `instance_tuple_not_found` - The metadata template was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error when an instance of this metadata template is already\npresent on the file.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "skills", + "tags": [ + "Skills" + ] + }, + "put": { + "operationId": "put_files_id_metadata_global_boxSkillsCards", + "summary": "Update Box Skill cards on file", + "description": "Updates one or more Box Skills metadata cards to a file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "application/json-patch+json": { + "schema": { + "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902)\nspecification for the changes to make to the metadata\ntemplate.\n\nThe changes are represented as a JSON array of\noperation objects.", + "type": "array", + "items": { + "type": "object", + "description": "An operation that replaces an existing card.", + "properties": { + "op": { + "description": "`replace`", + "type": "string", + "example": "replace", + "enum": [ + "replace" + ] + }, + "path": { + "description": "The JSON Path that represents the card to replace. In most cases\nthis will be in the format `/cards/{index}` where `index` is the\nzero-indexed position of the card in the list of cards.", + "type": "string", + "example": "/cards/0" + }, + "value": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/KeywordSkillCard" + }, + { + "$ref": "#/components/schemas/TimelineSkillCard" + }, + { + "$ref": "#/components/schemas/TranscriptSkillCard" + }, + { + "$ref": "#/components/schemas/StatusSkillCard" + } + ] + }, + { + "description": "The card to insert into the list of cards at the\nposition defined by `path`." + } + ] + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated metadata template, with the\ncustom template data included.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SkillCardsMetadata" + } + } + } + }, + "404": { + "description": "The requested file could not be found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "skills", + "tags": [ + "Skills" + ] + }, + "delete": { + "operationId": "delete_files_id_metadata_global_boxSkillsCards", + "summary": "Remove Box Skill cards from file", + "description": "Removes any Box Skills cards metadata from a file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned when the method was not allowed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "skills", + "tags": [ + "Skills" + ] + } + }, + "/files/{file_id}/watermark": { + "get": { + "operationId": "get_files_id_watermark", + "summary": "Get watermark on file", + "description": "Retrieve the watermark for a file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "200": { + "description": "Returns an object containing information about the\nwatermark associated for to this file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Watermark" + } + } + } + }, + "404": { + "description": "Returns an error if the file does not have a watermark applied.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_watermarks", + "tags": [ + "Watermarks (Files)" + ] + }, + "put": { + "operationId": "put_files_id_watermark", + "summary": "Apply watermark to file", + "description": "Applies or update a watermark on a file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "watermark": { + "description": "The watermark to imprint on the file", + "type": "object", + "properties": { + "imprint": { + "description": "The type of watermark to apply.\n\nCurrently only supports one option.", + "type": "string", + "example": "default", + "enum": [ + "default" + ] + } + }, + "required": [ + "imprint" + ] + } + }, + "required": [ + "watermark" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns an updated watermark if a watermark already\nexisted on this file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Watermark" + } + } + } + }, + "201": { + "description": "Returns a new watermark if no watermark existed on\nthis file yet.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Watermark" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_watermarks", + "tags": [ + "Watermarks (Files)" + ] + }, + "delete": { + "operationId": "delete_files_id_watermark", + "summary": "Remove watermark from file", + "description": "Removes the watermark from a file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "204": { + "description": "Removes the watermark and returns an empty response." + }, + "404": { + "description": "Returns an error if the file did not have\na watermark applied to it.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_watermarks", + "tags": [ + "Watermarks (Files)" + ] + } + }, + "/file_requests/{file_request_id}": { + "get": { + "operationId": "get_file_requests_id", + "summary": "Get file request", + "description": "Retrieves the information about a file request.", + "parameters": [ + { + "name": "file_request_id", + "in": "path", + "description": "The unique identifier that represent a file request.\n\nThe ID for any file request can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "123" + } + ], + "responses": { + "200": { + "description": "Returns a file request object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileRequest" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file request is not found, or the user does not\nhave access to the associated folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_request_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_requests", + "tags": [ + "File requests" + ] + }, + "put": { + "operationId": "put_file_requests_id", + "summary": "Update file request", + "description": "Updates a file request. This can be used to activate or\ndeactivate a file request.", + "parameters": [ + { + "name": "file_request_id", + "in": "path", + "description": "The unique identifier that represent a file request.\n\nThe ID for any file request can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "123" + }, + { + "name": "if-match", + "in": "header", + "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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileRequestUpdateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated file request object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileRequest" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned if the user does not have all the permissions to complete the\nupdate.\n\n* `access_denied_insufficient_permissions` when the authenticated user\ndoes not have access to update the file request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file request is not found, or the user does not\nhave access to the associated folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_request_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "412": { + "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file request. This indicates that the\nfile request has changed since it was last requested.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_requests", + "tags": [ + "File requests" + ] + }, + "delete": { + "operationId": "delete_file_requests_id", + "summary": "Delete file request", + "description": "Deletes a file request permanently.", + "parameters": [ + { + "name": "file_request_id", + "in": "path", + "description": "The unique identifier that represent a file request.\n\nThe ID for any file request can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "123" + } + ], + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_request_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_requests", + "tags": [ + "File requests" + ] + } + }, + "/file_requests/{file_request_id}/copy": { + "post": { + "operationId": "post_file_requests_id_copy", + "summary": "Copy file request", + "description": "Copies an existing file request that is already present on one folder,\nand applies it to another folder.", + "parameters": [ + { + "name": "file_request_id", + "in": "path", + "description": "The unique identifier that represent a file request.\n\nThe ID for any file request can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "123" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileRequestCopyRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Returns updated file request object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileRequest" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned if the user does not have all the permissions to complete the\nupdate.\n\n* `access_denied_insufficient_permissions` when the authenticated user\ndoes not have access to update the file request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file request is not found, or the user does not\nhave access to the associated folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_request_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_requests", + "tags": [ + "File requests" + ] + } + }, + "/folders/{folder_id}": { + "get": { + "operationId": "get_folders_id", + "summary": "Get folder information", + "description": "Retrieves details for a folder, including the first 100 entries\nin the folder.\n\nPassing `sort`, `direction`, `offset`, and `limit`\nparameters in query allows you to manage the\nlist of returned\n[folder items](r://folder--full#param-item-collection).\n\nTo fetch more items within the folder, use the\n[Get items in a folder](e://get-folders-id-items) endpoint.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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`?fields=metadata.enterprise_12345.contractTemplate`.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "if-none-match", + "in": "header", + "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + }, + { + "name": "boxapi", + "in": "header", + "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been\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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "shared_link=[link]&shared_link_password=[password]" + }, + { + "name": "sort", + "in": "query", + "description": "Defines the **second** attribute by which items\nare sorted.\n\nThe folder type affects the way the items\nare sorted:\n\n * **Standard folder**:\n Items are always sorted by\n their `type` first, with\n folders listed before files,\n and files listed\n before web links.\n\n * **Root folder**:\n This parameter is not supported\n for marker-based pagination\n on the root folder\n\n (the folder with an `id` of `0`).\n\n * **Shared folder with parent path\n to the associated folder visible to\n the collaborator**:\n Items are always sorted by\n their `type` first, with\n folders listed before files,\n and files listed\n before web links.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "id", + "name", + "date", + "size" + ] + }, + "example": "id" + }, + { + "name": "direction", + "in": "query", + "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "ASC", + "DESC" + ] + }, + "example": "ASC" + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a folder, including the first 100 entries in the folder.\nIf you used query parameters like\n`sort`, `direction`, `offset`, or `limit`\nthe *folder items list* will be affected accordingly.\n\nTo fetch more items within the folder, use the\n[Get items in a folder](e://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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Folder--Full" + } + } + } + }, + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `folder_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folders", + "tags": [ + "Folders" + ] + }, + "post": { + "operationId": "post_folders_id", + "summary": "Restore folder", + "description": "Restores a folder that has been moved to the trash.\n\nAn optional new parent ID can be provided to restore the folder to in case the\noriginal folder has been deleted.\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", + "in": "path", + "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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "An optional new name for the folder.", + "type": "string", + "example": "Restored Photos" + }, + "parent": { + "allOf": [ + { + "type": "object", + "description": "The parent for this item", + "properties": { + "id": { + "description": "The ID of parent item", + "type": "string", + "example": "123" + } + } + }, + { + "description": "Specifies an optional ID of a folder to restore the folder\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TrashFolderRestored" + } + } + } + }, + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if the folder is not in the trash.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "* Returned an error if there is a folder with the same name\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "trashed_folders", + "tags": [ + "Trashed folders" + ] + }, + "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.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "if-match", + "in": "header", + "description": "Ensures this item hasn't recently changed before\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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "The optional new name for this folder.", + "type": "string", + "example": "New Folder" + }, + "description": { + "description": "The optional description of this folder", + "type": "string", + "example": "Legal contracts for the new ACME deal", + "maxLength": 256, + "nullable": false + }, + "sync_state": { + "description": "Specifies whether a folder should be synced to a\nuser's device or not. This is used by Box Sync\n(discontinued) and is not used by Box Drive.", + "type": "string", + "example": "synced", + "enum": [ + "synced", + "not_synced", + "partially_synced" + ], + "nullable": false + }, + "can_non_owners_invite": { + "description": "Specifies if users who are not the owner\nof the folder can invite new collaborators to the folder.", + "type": "boolean", + "example": true + }, + "parent": { + "description": "The parent folder for this folder. Use this to move\nthe folder or to restore it out of the trash.", + "type": "object", + "properties": { + "id": { + "description": "The ID of the new parent folder", + "type": "string", + "example": "0" + } + } + }, + "shared_link": { + "allOf": [ + { + "description": "Defines a shared link for an item. Set this to `null` to remove\nthe shared link.", + "type": "object", + "properties": { + "access": { + "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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ] + }, + "password": { + "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", + "type": "string", + "example": "do-n8t-use-this-Password", + "nullable": true + }, + "vanity_name": { + "description": "Defines a custom vanity name to use in the shared link URL,\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.", + "type": "string", + "example": "my-shared-link" + }, + "unshared_at": { + "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "permissions": { + "type": "object", + "properties": { + "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", + "type": "boolean", + "example": true + } + } + } + } + }, + { + "description": "Enables the creation of a shared link for a folder." + } + ] + }, + "folder_upload_email": { + "allOf": [ + { + "title": "Folder upload email", + "type": "object", + "description": "The Write Folder Upload Email object", + "properties": { + "access": { + "description": "When this parameter has been set, users can email files\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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "collaborators" + ], + "nullable": false + } + } + }, + { + "description": "Setting this object enables the upload email address.\n\nThis email address can be used by users to directly\nupload files directly to the folder via email.\n\nSetting the value to `null` will disable the email address." + } + ], + "nullable": true + }, + "tags": { + "description": "The tags for this item. These tags are shown in\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.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "approved" + ], + "maxItems": 100, + "minItems": 1 + }, + "is_collaboration_restricted_to_enterprise": { + "description": "Specifies if new invites to this folder are restricted to users\nwithin the enterprise. This does not affect existing\ncollaborations.", + "type": "boolean", + "example": true + }, + "collections": { + "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]: e://get-collections", + "type": "array", + "items": { + "title": "Reference", + "description": "The bare basic reference for an object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this object", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type for this object", + "type": "string", + "example": "file" + } + } + }, + "nullable": true + }, + "can_non_owners_view_collaborators": { + "description": "Restricts collaborators who are not the owner of\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.", + "type": "boolean", + "example": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns a folder object for the updated folder\n\nNot all available fields are returned by default. Use the\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Folder--Full" + } + } + } + }, + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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.\n\n* `forbidden_by_policy`: Returned if copying a folder is\n forbidden due to information barrier restrictions.\n\nReturns an error if there are too many actions in the request body.\n\n* `operation_limit_exceeded`: Returned when the user passes any\nparameters in addition to the `parent.id` in the request body.\nThe calls to this endpoint have to be split up.\nThe first call needs to include only the `parent.id`,\nthe next call can include other parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if the folder or parent folder could not be found,\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "503": { + "description": "Returns an error when the operation takes longer\nthan 60 seconds. The operation will continue after\nthis response has been returned.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folders", + "tags": [ + "Folders" + ] + }, + "delete": { + "operationId": "delete_folders_id", + "summary": "Delete folder", + "description": "Deletes a folder, either permanently or by moving it to\nthe trash.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "if-match", + "in": "header", + "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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + }, + { + "name": "recursive", + "in": "query", + "description": "Delete a folder that is not empty by recursively deleting the\nfolder and all of its content.", + "required": false, + "schema": { + "type": "boolean" + }, + "example": true + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the folder is successfully deleted\nor moved to the trash." + }, + "400": { + "description": "Returns an error if the user makes a bad request.\n\n* `folder_not_empty`: Returned if the folder is not empty. Use the\n `recursive` query parameter to recursively delete the folder and\n its contents.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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 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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "* `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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "503": { + "description": "Returns an error when the operation takes longer\nthan 60 seconds. The operation will continue after\nthis response has been returned.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folders", + "tags": [ + "Folders" + ] + } + }, + "/folders/{folder_id}/app_item_associations": { + "get": { + "operationId": "get_folders_id_app_item_associations", + "summary": "List folder app item associations", + "description": "**This is a beta feature, which means that its availability might be limited.**\nReturns all app items the folder is associated with. This includes app items\nassociated with ancestors of the folder. Assuming the context user has access\nto the folder, the type/ids are revealed even if the context user does not\nhave **View** permission on the app item.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "application_type", + "in": "query", + "description": "If given, returns only app items for this application type", + "required": false, + "schema": { + "type": "string", + "nullable": false + }, + "example": "hubs" + } + ], + "responses": { + "200": { + "description": "Returns a collection of app item objects. If there are no\napp items on this folder an empty collection will be returned.\nThis list includes app items on ancestors of this folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppItemAssociations" + } + } + } + }, + "404": { + "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "app_item_associations", + "tags": [ + "App item associations" + ] + } + }, + "/folders/{folder_id}/items": { + "get": { + "operationId": "get_folders_id_items", + "summary": "List items in folder", + "description": "Retrieves a page of items in a folder. These items can be files,\nfolders, and web links.\n\nTo request more information about the folder itself, like its size,\nuse the [Get a folder](#get-folders-id) endpoint instead.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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`?fields=metadata.enterprise_12345.contractTemplate`.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "usemarker", + "in": "query", + "description": "Specifies whether to use marker-based pagination instead of\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.", + "required": false, + "schema": { + "type": "boolean" + }, + "example": true + }, + { + "name": "marker", + "in": "query", + "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`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "boxapi", + "in": "header", + "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been\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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "shared_link=[link]&shared_link_password=[password]" + }, + { + "name": "sort", + "in": "query", + "description": "Defines the **second** attribute by which items\nare sorted.\n\nThe folder type affects the way the items\nare sorted:\n\n * **Standard folder**:\n Items are always sorted by\n their `type` first, with\n folders listed before files,\n and files listed\n before web links.\n\n * **Root folder**:\n This parameter is not supported\n for marker-based pagination\n on the root folder\n\n (the folder with an `id` of `0`).\n\n * **Shared folder with parent path\n to the associated folder visible to\n the collaborator**:\n Items are always sorted by\n their `type` first, with\n folders listed before files,\n and files listed\n before web links.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "id", + "name", + "date", + "size" + ] + }, + "example": "id" + }, + { + "name": "direction", + "in": "query", + "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "ASC", + "DESC" + ] + }, + "example": "ASC" + } + ], + "responses": { + "200": { + "description": "Returns a collection of files, folders, and web links contained in a folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Items" + } + } + } + }, + "403": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `folder_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folders", + "tags": [ + "Folders" + ] + } + }, + "/folders": { + "post": { + "operationId": "post_folders", + "summary": "Create folder", + "description": "Creates a new empty folder within the specified parent folder.", + "parameters": [ + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "The name for the new folder.\n\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.", + "type": "string", + "example": "New Folder", + "maxLength": 255, + "minLength": 1 + }, + "parent": { + "description": "The parent folder to create the new folder within.", + "type": "object", + "properties": { + "id": { + "description": "The ID of parent folder", + "type": "string", + "example": "0" + } + }, + "required": [ + "id" + ] + }, + "folder_upload_email": { + "allOf": [ + { + "title": "Folder upload email", + "type": "object", + "description": "The Write Folder Upload Email object", + "properties": { + "access": { + "description": "When this parameter has been set, users can email files\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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "collaborators" + ], + "nullable": false + } + } + }, + { + "description": "Setting this object enables the upload email address.\n\nThis email address can be used by users to directly\nupload files directly to the folder via email." + } + ] + }, + "sync_state": { + "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.", + "type": "string", + "example": "synced", + "enum": [ + "synced", + "not_synced", + "partially_synced" + ], + "nullable": false + } + }, + "required": [ + "name", + "parent" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a folder object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Folder--Full" + } + } + } + }, + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folders", + "tags": [ + "Folders" + ] + } + }, + "/folders/{folder_id}/copy": { + "post": { + "operationId": "post_folders_id_copy", + "summary": "Copy folder", + "description": "Creates a copy of a folder within a destination folder.\n\nThe original folder will not be changed.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier of the folder to copy.\n\nThe ID for any folder can be determined\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.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "0" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "An optional new name for the copied folder.\n\nThere are some restrictions to the file name. Names containing\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.", + "type": "string", + "example": "New Folder", + "maxLength": 255, + "minLength": 1 + }, + "parent": { + "description": "The destination folder to copy the folder to.", + "type": "object", + "properties": { + "id": { + "description": "The ID of parent folder", + "type": "string", + "example": "0" + } + }, + "required": [ + "id" + ] + } + }, + "nullable": false, + "required": [ + "parent" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new folder object representing the copied folder.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Folder--Full" + } + } + } + }, + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error when the user does not have the\nright permissions to copy a folder.\n\n* `forbidden_by_policy`: Returned if copying a folder is\nforbidden due to information barrier restrictions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if either the source or destination folder\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", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "500": { + "description": "Returns an error when trying to copy the root folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folders", + "tags": [ + "Folders" + ] + } + }, + "/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.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Collaborations" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "list_collaborations", + "tags": [ + "Collaborations (List)" + ] + } + }, + "/folders/{folder_id}/trash": { + "get": { + "operationId": "get_folders_id_trash", + "summary": "Get trashed folder", + "description": "Retrieves a folder that has been moved to the trash.\n\nPlease note that only if the folder itself has been moved to the\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", + "in": "path", + "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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns the folder that was trashed,\nincluding information about when the it\nwas moved to the trash.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TrashFolder" + } + } + } + }, + "404": { + "description": "Returns an error if the folder can not be found directly\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "trashed_folders", + "tags": [ + "Trashed folders" + ] + }, + "delete": { + "operationId": "delete_folders_id_trash", + "summary": "Permanently remove folder", + "description": "Permanently deletes a folder that is in the trash.\nThis action cannot be undone.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + } + ], + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "trashed_folders", + "tags": [ + "Trashed folders" + ] + } + }, + "/folders/{folder_id}/metadata": { + "get": { + "operationId": "get_folders_id_metadata", + "summary": "List metadata instances on folder", + "description": "Retrieves all metadata for a given folder. This can not be used on the root\nfolder with ID `0`.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + } + ], + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Metadatas" + } + } + } + }, + "403": { + "description": "Returned when the request parameters are not valid.\n\n* `forbidden` - this operation is not allowed on the Root folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned when the user does not have access to the folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_metadata", + "tags": [ + "Metadata instances (Folders)" + ] + } + }, + "/folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo": { + "get": { + "operationId": "get_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", + "summary": "Get classification on folder", + "description": "Retrieves the classification metadata instance that\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", + "in": "path", + "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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + } + ], + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Classification" + } + } + } + }, + "403": { + "description": "Returned when the request parameters are not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the metadata template specified\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned when the method was not allowed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_classifications", + "tags": [ + "Classifications on folders" + ] + }, + "post": { + "operationId": "post_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", + "summary": "Add classification to folder", + "description": "Adds a classification to a folder by specifying the label of the\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", + "in": "path", + "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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "Box__Security__Classification__Key": { + "description": "The name of the classification to apply to this folder.\n\nTo list the available classifications in an enterprise,\nuse the classification API to retrieve the\n[classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)\nwhich lists all available classification keys.", + "type": "string", + "example": "Sensitive" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Returns the classification template instance\nthat was applied to the folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Classification" + } + } + } + }, + "400": { + "description": "Returns an error when the request body is not valid.\n\n* `schema_validation_failed` - The request body contains a value for\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the folder or metadata template was not found.\n\n* `not_found` - The folder could not be found, or the user does not have\naccess to the folder.\n* `instance_tuple_not_found` - The metadata template was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error when an instance of this metadata template is already\npresent on the folder.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_classifications", + "tags": [ + "Classifications on folders" + ] + }, + "put": { + "operationId": "put_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", + "summary": "Update classification on folder", + "description": "Updates a classification on a folder.\n\nThe classification can only be updated if a classification has already been\napplied to the folder before. When editing classifications, only values are\ndefined for the enterprise will be accepted.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "application/json-patch+json": { + "schema": { + "description": "A list containing the one change to make, to\nupdate the classification label.", + "type": "array", + "items": { + "type": "object", + "description": "The operation to perform on the classification\nmetadata template instance. In this case, it use\nused to replace the value stored for the\n`Box__Security__Classification__Key` field with a new\nvalue.", + "required": [ + "op", + "path", + "value" + ], + "properties": { + "op": { + "description": "`replace`", + "type": "string", + "example": "replace", + "enum": [ + "replace" + ] + }, + "path": { + "description": "Defines classifications \navailable in the enterprise.", + "type": "string", + "example": "/Box__Security__Classification__Key", + "enum": [ + "/Box__Security__Classification__Key" + ] + }, + "value": { + "description": "The name of the classification to apply to this folder.\n\nTo list the available classifications in an enterprise,\nuse the classification API to retrieve the\n[classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)\nwhich lists all available classification keys.", + "type": "string", + "example": "Sensitive" + } + } + }, + "required": [ + "items" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated classification metadata template instance.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Classification" + } + } + } + }, + "400": { + "description": "Returns an error when the request body is not valid.\n\n* `bad_request` - The request body format is not an array of valid JSON\nPatch operations.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "500": { + "description": "Returns an error in some edge cases when the request body is not a valid\narray of JSON Patch items.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_classifications", + "tags": [ + "Classifications on folders" + ] + }, + "delete": { + "operationId": "delete_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", + "summary": "Remove classification from folder", + "description": "Removes any classifications from a folder.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the classification is\nsuccessfully deleted." + }, + "400": { + "description": "Returned when the request parameters are not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the folder does not have any classification applied\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned when the method was not allowed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_classifications", + "tags": [ + "Classifications on folders" + ] + } + }, + "/folders/{folder_id}/metadata/{scope}/{template_key}": { + "get": { + "operationId": "get_folders_id_metadata_id_id", + "summary": "Get metadata instance on folder", + "description": "Retrieves the instance of a metadata template that has been applied to a\nfolder. This can not be used on the root folder with ID `0`.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "scope", + "in": "path", + "description": "The scope of the metadata template", + "required": true, + "schema": { + "type": "string", + "enum": [ + "global", + "enterprise" + ] + }, + "example": "global" + }, + { + "name": "template_key", + "in": "path", + "description": "The name of the metadata template", + "required": true, + "schema": { + "type": "string" + }, + "example": "properties" + } + ], + "responses": { + "201": { + "description": "An instance of the metadata template that includes\nadditional \"key:value\" pairs defined by the user or\nan application.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Metadata--Full" + } + } + } + }, + "403": { + "description": "Returned when the request parameters are not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the metadata template specified\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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`.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_metadata", + "tags": [ + "Metadata instances (Folders)" + ] + }, + "post": { + "operationId": "post_folders_id_metadata_id_id", + "summary": "Create metadata instance on folder", + "description": "Applies an instance of a metadata template to a folder.\n\nIn most cases only values that are present in the metadata template\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", + "in": "path", + "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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "scope", + "in": "path", + "description": "The scope of the metadata template", + "required": true, + "schema": { + "type": "string", + "enum": [ + "global", + "enterprise" + ] + }, + "example": "global" + }, + { + "name": "template_key", + "in": "path", + "description": "The name of the metadata template", + "required": true, + "schema": { + "type": "string" + }, + "example": "properties" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "example": { + "name": "Aaron Levie" + }, + "additionalProperties": { + "allOf": [ + {}, + { + "example": "Aaron Levie" + }, + { + "description": "A value for each of the fields that are present on the metadata\ntemplate.\nFor the `global.properties` template this can be a list of zero\nor more fields, as this template allows for any generic key-value\npairs to be stored in 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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Metadata--Full" + } + } + } + }, + "400": { + "description": "Returns an error when the request body is not valid.\n\n* `schema_validation_failed` - The request body contains a value for\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the folder or metadata template was not found.\n\n* `not_found` - The folder could not be found, or the user does not have\naccess to the folder.\n* `instance_tuple_not_found` - The metadata template was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error when an instance of this metadata template is already\npresent on the folder.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_metadata", + "tags": [ + "Metadata instances (Folders)" + ], + "x-box-enable-explorer": false + }, + "put": { + "operationId": "put_folders_id_metadata_id_id", + "summary": "Update metadata instance on folder", + "description": "Updates a piece of metadata on a folder.\n\nThe metadata instance can only be updated if the template has already been\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", + "in": "path", + "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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "scope", + "in": "path", + "description": "The scope of the metadata template", + "required": true, + "schema": { + "type": "string", + "enum": [ + "global", + "enterprise" + ] + }, + "example": "global" + }, + { + "name": "template_key", + "in": "path", + "description": "The name of the metadata template", + "required": true, + "schema": { + "type": "string" + }, + "example": "properties" + } + ], + "requestBody": { + "content": { + "application/json-patch+json": { + "schema": { + "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902)\nspecification for the changes to make to the metadata\ninstance.\n\nThe changes are represented as a JSON array of\noperation objects.", + "type": "array", + "items": { + "title": "A metadata instance update operation", + "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a\nchange to make to the metadata instance.", + "type": "object", + "properties": { + "op": { + "description": "The type of change to perform on the template. Some\nof these are hazardous as they will change existing templates.", + "type": "string", + "example": "add", + "enum": [ + "add", + "replace", + "remove", + "test", + "move", + "copy" + ] + }, + "path": { + "description": "The location in the metadata JSON object\nto apply the changes to, in the format of a\n[JSON-Pointer](https://tools.ietf.org/html/rfc6901).\n\nThe path must always be prefixed with a `/` to represent the root\nof the template. The characters `~` and `/` are reserved\ncharacters and must be escaped in the key.", + "type": "string", + "example": "/currentState" + }, + "value": { + "description": "The value to be set or tested.\n\nRequired for `add`, `replace`, and `test` operations. For `add`,\nif the value exists already the previous value will be overwritten\nby the new value. For `replace`, the value must exist before\nreplacing.\n\nFor `test`, the existing value at the `path` location must match\nthe specified value.", + "type": "string", + "example": "reviewed" + }, + "from": { + "description": "The location in the metadata JSON object to move or copy a value\nfrom. Required for `move` or `copy` operations and must be in the\nformat of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901).", + "type": "string", + "example": "/nextState" + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated metadata template instance, with the\ncustom template data included.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Metadata--Full" + } + } + } + }, + "400": { + "description": "Returns an error when the request body is not valid.\n\n* `bad_request` - The request body format is not an array of valid JSON\nPatch objects.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "500": { + "description": "Returns an error in some edge cases when the request body is not a valid\narray of JSON Patch items.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_metadata", + "tags": [ + "Metadata instances (Folders)" + ] + }, + "delete": { + "operationId": "delete_folders_id_metadata_id_id", + "summary": "Remove metadata instance from folder", + "description": "Deletes a piece of folder metadata.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "scope", + "in": "path", + "description": "The scope of the metadata template", + "required": true, + "schema": { + "type": "string", + "enum": [ + "global", + "enterprise" + ] + }, + "example": "global" + }, + { + "name": "template_key", + "in": "path", + "description": "The name of the metadata template", + "required": true, + "schema": { + "type": "string" + }, + "example": "properties" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the metadata is\nsuccessfully deleted." + }, + "400": { + "description": "Returned when the request parameters are not valid. This may happen of the\n`scope` is not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the folder does not have an instance of the metadata\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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`.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_metadata", + "tags": [ + "Metadata instances (Folders)" + ] + } + }, + "/folders/trash/items": { + "get": { + "operationId": "get_folders_trash_items", + "summary": "List 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", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + }, + { + "name": "usemarker", + "in": "query", + "description": "Specifies whether to use marker-based pagination instead of\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.", + "required": false, + "schema": { + "type": "boolean" + }, + "example": true + }, + { + "name": "marker", + "in": "query", + "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`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "direction", + "in": "query", + "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "ASC", + "DESC" + ] + }, + "example": "ASC" + }, + { + "name": "sort", + "in": "query", + "description": "Defines the **second** attribute by which items\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.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "name", + "date", + "size" + ] + }, + "example": "name" + } + ], + "responses": { + "200": { + "description": "Returns a list of items that have been deleted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Items" + } + } + } + }, + "400": { + "description": "Returns an error if some of the parameters are missing or\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`.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "trashed_items", + "tags": [ + "Trashed items" + ] + } + }, + "/folders/{folder_id}/watermark": { + "get": { + "operationId": "get_folders_id_watermark", + "summary": "Get watermark for folder", + "description": "Retrieve the watermark for a folder.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + } + ], + "responses": { + "200": { + "description": "Returns an object containing information about the\nwatermark associated for to this folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Watermark" + } + } + } + }, + "404": { + "description": "Returns an error if the folder does not have a watermark applied.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_watermarks", + "tags": [ + "Watermarks (Folders)" + ] + }, + "put": { + "operationId": "put_folders_id_watermark", + "summary": "Apply watermark to folder", + "description": "Applies or update a watermark on a folder.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "watermark": { + "description": "The watermark to imprint on the folder", + "type": "object", + "properties": { + "imprint": { + "description": "The type of watermark to apply.\n\nCurrently only supports one option.", + "type": "string", + "example": "default", + "enum": [ + "default" + ] + } + }, + "required": [ + "imprint" + ] + } + }, + "required": [ + "watermark" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns an updated watermark if a watermark already\nexisted on this folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Watermark" + } + } + } + }, + "201": { + "description": "Returns a new watermark if no watermark existed on\nthis folder yet.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Watermark" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_watermarks", + "tags": [ + "Watermarks (Folders)" + ] + }, + "delete": { + "operationId": "delete_folders_id_watermark", + "summary": "Remove watermark from folder", + "description": "Removes the watermark from a folder.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + } + ], + "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", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_watermarks", + "tags": [ + "Watermarks (Folders)" + ] + } + }, + "/folder_locks": { + "get": { + "operationId": "get_folder_locks", + "summary": "List folder locks", + "description": "Retrieves folder lock details for a given folder.\n\nYou must be authenticated as the owner or co-owner of the folder to\nuse this endpoint.", + "parameters": [ + { + "name": "folder_id", + "in": "query", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + } + ], + "responses": { + "200": { + "description": "Returns details for all folder locks applied to the folder, including the\nlock type and user that applied the lock.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FolderLocks" + } + } + } + }, + "403": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `folder_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_locks", + "tags": [ + "Folder Locks" + ] + }, + "post": { + "operationId": "post_folder_locks", + "summary": "Create folder lock", + "description": "Creates a folder lock on a folder, preventing it from being moved and/or\ndeleted.\n\nYou must be authenticated as the owner or co-owner of the folder to\nuse this endpoint.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "locked_operations": { + "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`.", + "type": "object", + "properties": { + "move": { + "description": "Whether moving the folder should be locked.", + "type": "boolean", + "example": true + }, + "delete": { + "description": "Whether deleting the folder should be locked.", + "example": true, + "type": "boolean" + } + }, + "required": [ + "move", + "delete" + ] + }, + "folder": { + "description": "The folder to apply the lock to.", + "type": "object", + "properties": { + "type": { + "description": "The content type the lock is being applied to. Only `folder`\nis supported.", + "type": "string", + "example": "folder" + }, + "id": { + "description": "The ID of the folder.", + "type": "string", + "example": "1234567890" + } + }, + "required": [ + "type", + "id" + ] + } + }, + "required": [ + "folder" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns the instance of the folder lock that was applied to the folder,\nincluding the user that applied the lock and the operations set.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FolderLock" + } + } + } + }, + "400": { + "description": "Returns an error when the request body is not valid.\n\n* `schema_validation_failed` - The request body contains a value for\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the folder was not found.\n\n* `not_found` - The folder could not be found, the user does not have\naccess to the folder, or the user making call is not an owner or co-owner\nof folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_locks", + "tags": [ + "Folder Locks" + ], + "x-box-enable-explorer": false + } + }, + "/folder_locks/{folder_lock_id}": { + "delete": { + "operationId": "delete_folder_locks_id", + "summary": "Delete folder lock", + "description": "Deletes a folder lock on a given folder.\n\nYou must be authenticated as the owner or co-owner of the folder to\nuse this endpoint.", + "parameters": [ + { + "name": "folder_lock_id", + "in": "path", + "description": "The ID of the folder lock.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the folder lock is successfully deleted." + }, + "403": { + "description": "Returns an error if the user does not have the required\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "folder_locks", + "tags": [ + "Folder Locks" + ] + } + }, + "/metadata_templates": { + "get": { + "operationId": "get_metadata_templates", + "summary": "Find metadata template by instance ID", + "description": "Finds a metadata template by searching for the ID of an instance of the\ntemplate.", + "parameters": [ + { + "name": "metadata_instance_id", + "in": "query", + "description": "The ID of an instance of the metadata template to find.", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + }, + "example": "01234500-12f1-1234-aa12-b1d234cb567e" + } + ], + "responses": { + "200": { + "description": "Returns a list containing the 1 metadata template that matches the\ninstance ID.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataTemplates" + } + } + } + }, + "400": { + "description": "Returned when the request parameters are not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ] + } + }, + "/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema": { + "get": { + "operationId": "get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema", + "summary": "List all classifications", + "description": "Retrieves the classification metadata template and lists all the\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClassificationTemplate" + } + } + } + }, + "400": { + "description": "Returned if any of the request parameters are not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned when a template name is not correct. Please make sure\nthe URL for the request is correct.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "classifications", + "tags": [ + "Classifications" + ] + } + }, + "/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#add": { + "put": { + "operationId": "put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#add", + "summary": "Add classification", + "description": "Adds one or more new classifications to the list of classifications\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`.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "An array that contains one or more classifications to add to\nthe enterprise's list of classifications.", + "type": "array", + "items": { + "type": "object", + "description": "A single classification to add to the enterprise.", + "required": [ + "op", + "fieldKey", + "data" + ], + "properties": { + "op": { + "description": "The type of change to perform on the classification\nobject.", + "type": "string", + "example": "addEnumOption", + "enum": [ + "addEnumOption" + ] + }, + "fieldKey": { + "description": "Defines classifications \navailable in the enterprise.", + "type": "string", + "example": "Box__Security__Classification__Key", + "enum": [ + "Box__Security__Classification__Key" + ] + }, + "data": { + "description": "The details of the classification to add.", + "type": "object", + "properties": { + "key": { + "description": "The label of the classification as shown in the web and\nmobile interfaces. This is the only field required to\nadd a classification.", + "type": "string", + "example": "Sensitive" + }, + "staticConfig": { + "description": "A static configuration for the classification.", + "type": "object", + "properties": { + "classification": { + "description": "Additional details for the classification.", + "type": "object", + "properties": { + "classificationDefinition": { + "description": "A longer description of the classification.", + "type": "string", + "example": "Sensitive information that must not be shared." + }, + "colorID": { + "description": "An internal Box identifier used to assign a color to\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", + "type": "integer", + "format": "int64", + "example": 4 + } + } + } + } + } + }, + "required": [ + "key" + ] + } + } + }, + "required": [ + "items" + ] + } + } + } + }, + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClassificationTemplate" + } + } + } + }, + "400": { + "description": "Returned if any of the request parameters are not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned when a template name is not correct. Please make sure\nthe URL for the request is correct.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "classifications", + "tags": [ + "Classifications" + ] + } + }, + "/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#update": { + "put": { + "operationId": "put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#update", + "summary": "Update classification", + "description": "Updates the labels and descriptions of one or more classifications\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`.", + "requestBody": { + "content": { + "application/json-patch+json": { + "schema": { + "description": "An array that contains one or more classifications to update.", + "type": "array", + "items": { + "type": "object", + "description": "A single classification to update.", + "required": [ + "op", + "fieldKey", + "enumOptionKey", + "data" + ], + "properties": { + "op": { + "description": "The type of change to perform on the classification\nobject.", + "type": "string", + "example": "editEnumOption", + "enum": [ + "editEnumOption" + ] + }, + "fieldKey": { + "description": "Defines classifications \navailable in the enterprise.", + "type": "string", + "example": "Box__Security__Classification__Key", + "enum": [ + "Box__Security__Classification__Key" + ] + }, + "enumOptionKey": { + "description": "The original label of the classification to change.", + "type": "string", + "example": "Sensitive" + }, + "data": { + "description": "The details of the updated classification.", + "type": "object", + "properties": { + "key": { + "description": "A new label for the classification, as it will be\nshown in the web and mobile interfaces.", + "type": "string", + "example": "Very Sensitive" + }, + "staticConfig": { + "description": "A static configuration for the classification.", + "type": "object", + "properties": { + "classification": { + "description": "Additional details for the classification.", + "type": "object", + "properties": { + "classificationDefinition": { + "description": "A longer description of the classification.", + "type": "string", + "example": "Sensitive information that must not be shared." + }, + "colorID": { + "description": "An internal Box identifier used to assign a color to\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", + "type": "integer", + "format": "int64", + "example": 4 + } + } + } + } + } + }, + "required": [ + "key" + ] + } + } + }, + "required": [ + "items" + ] + } + } + } + }, + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClassificationTemplate" + } + } + } + }, + "400": { + "description": "Returned if any of the request parameters are not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned when a template name is not correct. Please make sure\nthe URL for the request is correct.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "classifications", + "tags": [ + "Classifications" + ] + } + }, + "/metadata_templates/{scope}/{template_key}/schema": { + "get": { + "operationId": "get_metadata_templates_id_id_schema", + "summary": "Get metadata template by name", + "description": "Retrieves a metadata template by its `scope` and `templateKey` values.\n\nTo find the `scope` and `templateKey` for a template, list all templates for\nan enterprise or globally, or list all templates applied to a file or folder.", + "parameters": [ + { + "name": "scope", + "in": "path", + "description": "The scope of the metadata template", + "required": true, + "schema": { + "type": "string", + "enum": [ + "global", + "enterprise" + ] + }, + "example": "global" + }, + { + "name": "template_key", + "in": "path", + "description": "The name of the metadata template", + "required": true, + "schema": { + "type": "string" + }, + "example": "properties" + } + ], + "responses": { + "200": { + "description": "Returns the metadata template matching the `scope`\nand `template` name.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataTemplate" + } + } + } + }, + "400": { + "description": "Returned if any of the request parameters are not valid.\n\n* `bad_request`: Often returned when the scope of the template is not\n recognised. Please make sure to use either `enterprise` or `global` as\n the `scope` value.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned when a template with the given `scope` and `template_key` can not\nbe found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ] + }, + "put": { + "operationId": "put_metadata_templates_id_id_schema", + "summary": "Update metadata template", + "description": "Updates a metadata template.\n\nThe metadata template can only be updated if the template\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", + "in": "path", + "description": "The scope of the metadata template", + "required": true, + "schema": { + "type": "string", + "enum": [ + "global", + "enterprise" + ] + }, + "example": "global" + }, + { + "name": "template_key", + "in": "path", + "description": "The name of the metadata template", + "required": true, + "schema": { + "type": "string" + }, + "example": "properties" + } + ], + "requestBody": { + "content": { + "application/json-patch+json": { + "schema": { + "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902)\nspecification for the changes to make to the metadata\ntemplate.\n\nThe changes are represented as a JSON array of\noperation objects.", + "type": "array", + "items": { + "title": "A metadata template update operation", + "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a\nchange to make to the metadata instance.", + "type": "object", + "required": [ + "op" + ], + "properties": { + "op": { + "description": "The type of change to perform on the template. Some\nof these are hazardous as they will change existing templates.", + "type": "string", + "example": "addEnumOption", + "enum": [ + "editTemplate", + "addField", + "reorderFields", + "addEnumOption", + "reorderEnumOptions", + "reorderMultiSelectOptions", + "addMultiSelectOption", + "editField", + "removeField", + "editEnumOption", + "removeEnumOption", + "editMultiSelectOption", + "removeMultiSelectOption" + ] + }, + "data": { + "description": "The data for the operation. This will vary depending on the\noperation being performed.", + "type": "object", + "example": { + "name": "Aaron Levie" + }, + "additionalProperties": { + "allOf": [ + {}, + { + "example": "Aaron Levie" + }, + { + "description": "A value for each of the fields that are present\non the metadata template.\nFor the `global.properties` template this can be\na list of zero or more fields,\nas this template allows for any generic key-value pairs \nto be stored stored in the template." + } + ], + "x-box-example-key": "name" + } + }, + "fieldKey": { + "description": "For operations that affect a single field this defines the key of\nthe field that is affected.", + "type": "string", + "example": "category" + }, + "fieldKeys": { + "description": "For operations that affect multiple fields this defines the keys\nof the fields that are affected.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "category", + "name" + ] + }, + "enumOptionKey": { + "description": "For operations that affect a single `enum` option this defines\nthe key of the option that is affected.", + "type": "string", + "example": "option1" + }, + "enumOptionKeys": { + "description": "For operations that affect multiple `enum` options this defines\nthe keys of the options that are affected.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "option1", + "option2", + "option3" + ] + }, + "multiSelectOptionKey": { + "description": "For operations that affect a single multi select option this\ndefines the key of the option that is affected.", + "type": "string", + "example": "option1" + }, + "multiSelectOptionKeys": { + "description": "For operations that affect multiple multi select options this\ndefines the keys of the options that are affected.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "option1", + "option2", + "option3" + ] + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated metadata template, with the\ncustom template data included.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataTemplate" + } + } + } + }, + "400": { + "description": "The request body does not contain a valid metadata schema.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "The request body contains a scope that the user is not\nallowed to create templates for.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "The requested template could not be found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ] + }, + "delete": { + "operationId": "delete_metadata_templates_id_id_schema", + "summary": "Remove metadata template", + "description": "Delete a metadata template and its instances.\nThis deletion is permanent and can not be reversed.", + "parameters": [ + { + "name": "scope", + "in": "path", + "description": "The scope of the metadata template", + "required": true, + "schema": { + "type": "string", + "enum": [ + "global", + "enterprise" + ] + }, + "example": "global" + }, + { + "name": "template_key", + "in": "path", + "description": "The name of the metadata template", + "required": true, + "schema": { + "type": "string" + }, + "example": "properties" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the metadata\ntemplate is successfully deleted." + }, + "400": { + "description": "Request body does not contain a valid metadata schema.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Request body contains a scope that the user is not allowed to\ncreate a template for.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ] + } + }, + "/metadata_templates/{template_id}": { + "get": { + "operationId": "get_metadata_templates_id", + "summary": "Get metadata template by ID", + "description": "Retrieves a metadata template by its ID.", + "parameters": [ + { + "name": "template_id", + "in": "path", + "description": "The ID of the template", + "required": true, + "schema": { + "type": "string" + }, + "example": "f7a9891f" + } + ], + "responses": { + "200": { + "description": "Returns the metadata template that matches the ID.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataTemplate" + } + } + } + }, + "400": { + "description": "Returned if any of the request parameters are not valid.\n\n* `bad_request`: Often returned with a message when the ID of the template\n is not recognised.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataTemplate" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ] + } + }, + "/metadata_templates/global": { + "get": { + "operationId": "get_metadata_templates_global", + "summary": "List all global metadata templates", + "description": "Used to retrieve all generic, global metadata templates available to all\nenterprises using Box.", + "parameters": [ + { + "name": "marker", + "in": "query", + "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`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns all of the metadata templates available to all enterprises\nand their corresponding schema.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataTemplates" + } + } + } + }, + "400": { + "description": "Returned when the request parameters are not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ] + } + }, + "/metadata_templates/enterprise": { + "get": { + "operationId": "get_metadata_templates_enterprise", + "summary": "List all metadata templates for enterprise", + "description": "Used to retrieve all metadata templates created to be used specifically within\nthe user's enterprise", + "parameters": [ + { + "name": "marker", + "in": "query", + "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`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns all of the metadata templates within an enterprise\nand their corresponding schema.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataTemplates" + } + } + } + }, + "400": { + "description": "Returned when the request parameters are not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ] + } + }, + "/metadata_templates/schema": { + "post": { + "operationId": "post_metadata_templates_schema", + "summary": "Create metadata template", + "description": "Creates a new metadata template that can be applied to\nfiles and folders.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "scope": { + "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.", + "type": "string", + "example": "enterprise" + }, + "templateKey": { + "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`.", + "type": "string", + "example": "productInfo", + "maxLength": 64, + "pattern": "^[a-zA-Z_][-a-zA-Z0-9_]*$" + }, + "displayName": { + "description": "The display name of the template.", + "type": "string", + "example": "Product Info", + "maxLength": 4096 + }, + "hidden": { + "description": "Defines if this template is visible in the Box web app UI, or if\nit is purely intended for usage through the API.", + "type": "boolean", + "example": true, + "default": false + }, + "fields": { + "description": "An ordered list of template fields which are part of the template.\nEach field can be a regular text field, date field, number field,\nas well as a single or multi-select list.", + "type": "array", + "items": { + "title": "Metadata Field (Write)", + "description": "A field within a metadata template. Fields can be a basic text, date, or\nnumber field, or a list of options.", + "required": [ + "type", + "key", + "displayName" + ], + "type": "object", + "properties": { + "type": { + "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.", + "type": "string", + "example": "string", + "enum": [ + "string", + "float", + "date", + "enum", + "multiSelect" + ] + }, + "key": { + "description": "A unique identifier for the field. The identifier must\nbe unique within the template to which it belongs.", + "type": "string", + "example": "category", + "maxLength": 256 + }, + "displayName": { + "description": "The display name of the field as it is shown to the user in the web and\nmobile apps.", + "type": "string", + "example": "Category", + "maxLength": 4096 + }, + "description": { + "description": "A description of the field. This is not shown to the user.", + "type": "string", + "example": "The category", + "maxLength": 4096 + }, + "hidden": { + "description": "Whether this field is hidden in the UI for the user and can only be set\nthrough the API instead.", + "type": "boolean", + "example": true + }, + "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", + "example": "Category 1" + } + } + } + } + } + } + }, + "copyInstanceOnItemCopy": { + "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.", + "type": "boolean", + "example": true, + "default": false + } + }, + "required": [ + "scope", + "displayName" + ] + } + } + } + }, + "responses": { + "201": { + "description": "The schema representing the metadata template created.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataTemplate" + } + } + } + }, + "400": { + "description": "Returned if the request parameters or body is not valid.\n\n* `bad_request` when the body does not contain a valid request. In many\ncases this response will include extra details on what fields are missing.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned when the user does not have the permission to create the metadata\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "metadata_templates", + "tags": [ + "Metadata templates" + ], + "x-box-requires-admin": true + } + }, + "/metadata_templates/schema#classifications": { + "post": { + "operationId": "post_metadata_templates_schema#classifications", + "summary": "Add initial classifications", + "description": "When an enterprise does not yet have any classifications, this API call\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.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "scope": { + "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.", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise" + ] + }, + "templateKey": { + "description": "Defines the list of metadata templates.", + "type": "string", + "example": "securityClassification-6VMVochwUWo", + "enum": [ + "securityClassification-6VMVochwUWo" + ] + }, + "displayName": { + "description": "The name of the\ntemplate as shown in web and mobile interfaces.", + "type": "string", + "example": "Classification", + "enum": [ + "Classification" + ] + }, + "hidden": { + "description": "Determines if the classification template is\nhidden or available on web and mobile\ndevices.", + "type": "boolean", + "example": false + }, + "copyInstanceOnItemCopy": { + "description": "Determines if classifications are\ncopied along when the file or folder is\ncopied.", + "type": "boolean", + "example": false + }, + "fields": { + "description": "The classification template requires exactly\none field, which holds\nall the valid classification values.", + "type": "array", + "items": { + "required": [ + "type", + "key", + "displayName", + "options" + ], + "type": "object", + "description": "The `enum` field which holds all the valid classification\nvalues.", + "properties": { + "type": { + "description": "The type of the field\nthat is always enum.", + "type": "string", + "example": "enum", + "enum": [ + "enum" + ] + }, + "key": { + "description": "Defines classifications \navailable in the enterprise.", + "type": "string", + "example": "Box__Security__Classification__Key", + "enum": [ + "Box__Security__Classification__Key" + ] + }, + "displayName": { + "description": "A display name for the classification.", + "type": "string", + "example": "Classification", + "enum": [ + "Classification" + ] + }, + "hidden": { + "description": "Determines if the classification\ntemplate is\nhidden or available on\nweb and mobile\ndevices.", + "type": "boolean", + "example": false + }, + "options": { + "description": "The actual list of classifications that are present on\nthis template.", + "type": "array", + "items": { + "required": [ + "key" + ], + "type": "object", + "description": "An individual classification.", + "properties": { + "key": { + "description": "The display name and key this classification. This\nwill be show in the Box UI.", + "type": "string", + "example": "Sensitive" + }, + "staticConfig": { + "description": "Additional information about the classification.", + "type": "object", + "properties": { + "classification": { + "description": "Additional information about the classification.", + "type": "object", + "properties": { + "classificationDefinition": { + "description": "A longer description of the classification.", + "type": "string", + "example": "Sensitive information" + }, + "colorID": { + "description": "An identifier used to assign a color to\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", + "type": "integer", + "format": "int64", + "example": 4 + } + } + } + } + } + } + } + } + } + } + } + }, + "required": [ + "scope", + "displayName", + "fields", + "templateKey" + ] + } + } + } + }, + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClassificationTemplate" + } + } + } + }, + "400": { + "description": "Returned if any of the request parameters are not valid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned when a template name is not correct. Please make sure\nthe URL for the request is correct.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "classifications", + "tags": [ + "Classifications" + ] + } + }, + "/metadata_cascade_policies": { + "get": { + "operationId": "get_metadata_cascade_policies", + "summary": "List 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", + "description": "Specifies which folder to return policies for. This can not be used on the\nroot folder with ID `0`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "31232" + }, + { + "name": "owner_enterprise_id", + "in": "query", + "description": "The ID of the enterprise ID for which to find metadata\ncascade policies. If not specified, it defaults to the\ncurrent enterprise.", + "schema": { + "type": "string" + }, + "example": "31232" + }, + { + "name": "marker", + "in": "query", + "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`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a list of metadata cascade policies", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataCascadePolicies" + } + } + } + }, + "400": { + "description": "Returns an error when any of the parameters are not in a valid format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error when the folder can not be accessed. This error often\nhappens when accessing the root folder with ID `0`.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the folder can not be found or the user does not\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "metadata_cascade_policies", + "tags": [ + "Metadata cascade policies" + ] + }, + "post": { + "operationId": "post_metadata_cascade_policies", + "summary": "Create metadata cascade policy", + "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.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "folder_id": { + "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.", + "type": "string", + "example": "1234567" + }, + "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", + "example": "enterprise", + "enum": [ + "global", + "enterprise" + ] + }, + "templateKey": { + "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", + "type": "string", + "example": "productInfo" + } + }, + "required": [ + "folder_id", + "scope", + "templateKey" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new of metadata cascade policy", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataCascadePolicy" + } + } + } + }, + "400": { + "description": "Returns an error when any of the parameters are not in a valid format.\n\n* `bad_request` - Either the `scope`, `templateKey`, or `folder_id` are\nnot in a valid format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error when trying to apply a policy to a restricted folder, for\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the template or folder can not be found, or when the\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConflictError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "metadata_cascade_policies", + "tags": [ + "Metadata cascade policies" + ] + } + }, + "/metadata_cascade_policies/{metadata_cascade_policy_id}": { + "get": { + "operationId": "get_metadata_cascade_policies_id", + "summary": "Get metadata cascade policy", + "description": "Retrieve a specific metadata cascade policy assigned to a folder.", + "parameters": [ + { + "name": "metadata_cascade_policy_id", + "in": "path", + "description": "The ID of the metadata cascade policy.", + "required": true, + "schema": { + "type": "string" + }, + "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" + } + ], + "responses": { + "200": { + "description": "Returns a metadata cascade policy", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataCascadePolicy" + } + } + } + }, + "404": { + "description": "Returns an error when the policy can not be found or the user does not\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "metadata_cascade_policies", + "tags": [ + "Metadata cascade policies" + ] + }, + "delete": { + "operationId": "delete_metadata_cascade_policies_id", + "summary": "Remove metadata cascade policy", + "description": "Deletes a metadata cascade policy.", + "parameters": [ + { + "name": "metadata_cascade_policy_id", + "in": "path", + "description": "The ID of the metadata cascade policy.", + "required": true, + "schema": { + "type": "string" + }, + "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the policy\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "metadata_cascade_policies", + "tags": [ + "Metadata cascade policies" + ] + } + }, + "/metadata_cascade_policies/{metadata_cascade_policy_id}/apply": { + "post": { + "operationId": "post_metadata_cascade_policies_id_apply", + "summary": "Force-apply metadata cascade policy to folder", + "description": "Force the metadata on a folder with a metadata cascade policy to be applied to\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", + "in": "path", + "description": "The ID of the cascade policy to force-apply.", + "required": true, + "schema": { + "type": "string" + }, + "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "conflict_resolution": { + "description": "Describes the desired behavior when dealing with the conflict\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.", + "type": "string", + "example": "none", + "enum": [ + "none", + "overwrite" + ] + } + }, + "required": [ + "conflict_resolution" + ] + } + } + } + }, + "responses": { + "202": { + "description": "Returns an empty response when the API call was successful. The metadata\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "metadata_cascade_policies", + "tags": [ + "Metadata cascade policies" + ] + } + }, + "/metadata_queries/execute_read": { + "post": { + "operationId": "post_metadata_queries_execute_read", + "summary": "Query files/folders by metadata", + "description": "Create a search using SQL-like syntax to return items that match specific\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.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataQuery" + } + } + } + }, + "responses": { + "200": { + "description": "Returns a list of files and folders that match this metadata query.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetadataQueryResults" + } + } + } + }, + "400": { + "description": "Returns an error when the request body is not valid.\n\n* `invalid_query` - Any of the provided body parameters might be\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\" }`.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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 was not found. Please make sure\nto use the full template scope including the enterprise ID, like\n`enterprise_12345`.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "search", + "tags": [ + "Search" + ] + } + }, + "/comments/{comment_id}": { + "get": { + "operationId": "get_comments_id", + "summary": "Get comment", + "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", + "in": "path", + "description": "The ID of the comment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns a full comment object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Comment--Full" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "comments", + "tags": [ + "Comments" + ] + }, + "put": { + "operationId": "put_comments_id", + "summary": "Update comment", + "description": "Update the message of a comment.", + "parameters": [ + { + "name": "comment_id", + "in": "path", + "description": "The ID of the comment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "description": "The text of the comment to update", + "type": "string", + "example": "Review completed!" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated comment object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Comment--Full" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "comments", + "tags": [ + "Comments" + ] + }, + "delete": { + "operationId": "delete_comments_id", + "summary": "Remove comment", + "description": "Permanently deletes a comment.", + "parameters": [ + { + "name": "comment_id", + "in": "path", + "description": "The ID of the comment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the comment has been deleted." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "comments", + "tags": [ + "Comments" + ] + } + }, + "/comments": { + "post": { + "operationId": "post_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", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "description": "The text of the comment.\n\nTo mention a user, use the `tagged_message`\nparameter instead.", + "type": "string", + "example": "Review completed!" + }, + "tagged_message": { + "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.", + "type": "string", + "example": "@[1234:John] Review completed!" + }, + "item": { + "description": "The item to attach the comment to.", + "type": "object", + "properties": { + "id": { + "description": "The ID of the item", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type of the item that this comment will be placed on.", + "type": "string", + "example": "file", + "enum": [ + "file", + "comment" + ] + } + }, + "required": [ + "id", + "type" + ] + } + }, + "required": [ + "message", + "item" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns the newly created comment object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Comment--Full" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "comments", + "tags": [ + "Comments" + ], + "x-box-enable-explorer": false + } + }, + "/collaborations/{collaboration_id}": { + "get": { + "operationId": "get_collaborations_id", + "summary": "Get collaboration", + "description": "Retrieves a single collaboration.", + "parameters": [ + { + "name": "collaboration_id", + "in": "path", + "description": "The ID of the collaboration", + "required": true, + "schema": { + "type": "string" + }, + "example": "1234" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns a collaboration object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Collaboration" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "user_collaborations", + "tags": [ + "Collaborations" + ] + }, + "put": { + "operationId": "put_collaborations_id", + "summary": "Update collaboration", + "description": "Updates a collaboration.\nCan be used to change the owner of an item, or to\naccept collaboration invites.", + "parameters": [ + { + "name": "collaboration_id", + "in": "path", + "description": "The ID of the collaboration", + "required": true, + "schema": { + "type": "string" + }, + "example": "1234" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "role": { + "description": "The level of access granted.", + "type": "string", + "example": "editor", + "enum": [ + "editor", + "viewer", + "previewer", + "uploader", + "previewer uploader", + "viewer uploader", + "co-owner", + "owner" + ] + }, + "status": { + "description": "\nSet the status of a `pending` collaboration invitation,\neffectively accepting, or rejecting the invite.", + "type": "string", + "example": "accepted", + "enum": [ + "pending", + "accepted", + "rejected" + ] + }, + "expires_at": { + "description": "Update the expiration date for the collaboration. At this date,\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.", + "type": "string", + "format": "date-time", + "example": "2019-08-29T23:59:00-07:00" + }, + "can_view_path": { + "description": "Determines if the invited users can see the entire parent path to\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.\n\nOnly owner or co-owners can invite collaborators with a `can_view_path` of\n`true`.\n\n`can_view_path` can only be used for folder collaborations.", + "type": "boolean", + "example": true + } + }, + "required": [ + "role" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns an updated collaboration object unless the owner has changed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Collaboration" + } + } + } + }, + "204": { + "description": "If the role is changed to `owner`, the collaboration is deleted\nand a new collaboration is created. The previous `owner` of\nthe old collaboration will be a `co-owner` on the new collaboration." + }, + "403": { + "description": "Returns an error if the authenticated user does not have the right\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "user_collaborations", + "tags": [ + "Collaborations" + ] + }, + "delete": { + "operationId": "delete_collaborations_id", + "summary": "Remove collaboration", + "description": "Deletes a single collaboration.", + "parameters": [ + { + "name": "collaboration_id", + "in": "path", + "description": "The ID of the collaboration", + "required": true, + "schema": { + "type": "string" + }, + "example": "1234" + } + ], + "responses": { + "204": { + "description": "A blank response is returned if the collaboration was\nsuccessfully deleted." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "user_collaborations", + "tags": [ + "Collaborations" + ] + } + }, + "/collaborations": { + "get": { + "operationId": "get_collaborations", + "summary": "List pending collaborations", + "description": "Retrieves all pending collaboration invites for this user.", + "parameters": [ + { + "name": "status", + "in": "query", + "description": "The status of the collaborations to retrieve", + "required": true, + "schema": { + "type": "string", + "enum": [ + "pending" + ] + }, + "example": "pending" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a collection of pending collaboration objects.\n\nIf the user has no pending collaborations, the collection\nwill be empty.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Collaborations" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "list_collaborations", + "tags": [ + "Collaborations (List)" + ] + }, + "post": { + "operationId": "post_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.\n\nIf collaboration is in `pending` status, the following fields\nare redacted:\n- `login` and `name` are hidden if a collaboration was created\nusing `user_id`,\n- `name` is hidden if a collaboration was created using `login`.", + "parameters": [ + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "notify", + "in": "query", + "description": "Determines if users should receive email notification\nfor the action performed.", + "required": false, + "schema": { + "type": "boolean" + }, + "example": true + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "item": { + "description": "The item to attach the comment to.", + "type": "object", + "properties": { + "type": { + "description": "The type of the item that this collaboration will be\ngranted access to", + "type": "string", + "example": "file", + "enum": [ + "file", + "folder" + ] + }, + "id": { + "description": "The ID of the item that will be granted access to", + "type": "string", + "example": "11446498" + } + } + }, + "accessible_by": { + "description": "The user or group to give access to the item.", + "type": "object", + "properties": { + "type": { + "description": "The type of collaborator to invite.", + "type": "string", + "example": "user", + "enum": [ + "user", + "group" + ] + }, + "id": { + "description": "The ID of the user or group.\n\nAlternatively, use `login` to specify a user by email\naddress.", + "type": "string", + "example": "23522323" + }, + "login": { + "description": "The email address of the user to grant access to the item.\n\nAlternatively, use `id` to specify a user by user ID.", + "type": "string", + "example": "john@example.com" + } + }, + "required": [ + "type" + ] + }, + "role": { + "description": "The level of access granted.", + "type": "string", + "example": "editor", + "enum": [ + "editor", + "viewer", + "previewer", + "uploader", + "previewer uploader", + "viewer uploader", + "co-owner" + ] + }, + "is_access_only": { + "description": "If set to `true`, collaborators have access to\nshared items, but such items won't be visible in the\nAll Files list. Additionally, collaborators won't\nsee the the path to the root folder for the\nshared item.", + "type": "boolean", + "example": true + }, + "can_view_path": { + "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.\n\nOnly owner or co-owners can invite collaborators with a `can_view_path` of\n`true`.\n\n`can_view_path` can only be used for folder collaborations.", + "type": "boolean", + "example": true + }, + "expires_at": { + "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.", + "type": "string", + "format": "date-time", + "example": "2019-08-29T23:59:00-07:00" + } + }, + "required": [ + "item", + "accessible_by", + "role" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new collaboration object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Collaboration" + } + } + } + }, + "403": { + "description": "Returns an error when the user does not have the\nright permissions to create the collaboration.\n\n* `forbidden_by_policy`: Creating a\ncollaboration is forbidden due to information\nbarrier restrictions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "user_collaborations", + "tags": [ + "Collaborations" + ] + } + }, + "/search": { + "get": { + "operationId": "get_search", + "summary": "Search for content", + "description": "Searches for files, folders, web links, and shared files across the\nusers content or across the entire enterprise.", + "parameters": [ + { + "name": "query", + "in": "query", + "description": "The string to search for. This query is matched against item names,\ndescriptions, text content of files, and various other fields of\nthe different item types.\n\nThis parameter supports a variety of operators to further refine\nthe results returns.\n\n* `\"\"` - by wrapping a query in double quotes only exact matches are\n returned by the API. Exact searches do not return search matches\n based on specific character sequences. Instead, they return\n matches based on phrases, that is, word sequences. For example:\n A search for `\"Blue-Box\"` may return search results including\n the sequence `\"blue.box\"`, `\"Blue Box\"`, and `\"Blue-Box\"`;\n any item containing the words `Blue` and `Box` consecutively, in\n the order specified.\n* `AND` - returns items that contain both the search terms. For\n example, a search for `marketing AND BoxWorks` returns items\n that have both `marketing` and `BoxWorks` within its text in any order.\n It does not return a result that only has `BoxWorks` in its text.\n* `OR` - returns items that contain either of the search terms. For\n example, a search for `marketing OR BoxWorks` returns a result that\n has either `marketing` or `BoxWorks` within its text. Using this\n operator is not necessary as we implicitly interpret multi-word\n queries as `OR` unless another supported boolean term is used.\n* `NOT` - returns items that do not contain the search term provided.\n For example, a search for `marketing AND NOT BoxWorks` returns a result\n that has only `marketing` within its text. Results containing\n `BoxWorks` are omitted.\n\nWe do not support lower case (that is,\n`and`, `or`, and `not`) or mixed case (that is, `And`, `Or`, and `Not`)\noperators.\n\nThis field is required unless the `mdfilters` parameter is defined.", + "required": false, + "schema": { + "type": "string" + }, + "example": "sales" + }, + { + "name": "scope", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "string", + "default": "user_content", + "enum": [ + "user_content", + "enterprise_content" + ] + }, + "example": "user_content" + }, + { + "name": "file_extensions", + "in": "query", + "description": "Limits the search results to any files that match any of the provided\nfile extensions. This list is a comma-separated list of file extensions\nwithout the dots.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "pdf", + "png", + "gif" + ], + "explode": false + }, + { + "name": "created_at_range", + "in": "query", + "description": "Limits the search results to any items created within\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "2014-05-15T13:35:01-07:00", + "2014-05-17T13:35:01-07:00" + ], + "explode": false + }, + { + "name": "updated_at_range", + "in": "query", + "description": "Limits the search results to any items updated within\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "2014-05-15T13:35:01-07:00", + "2014-05-17T13:35:01-07:00" + ], + "explode": false + }, + { + "name": "size_range", + "in": "query", + "description": "Limits the search results to any items with a size within\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "integer" + } + }, + "example": [ + 1000000, + 5000000 + ], + "explode": false + }, + { + "name": "owner_user_ids", + "in": "query", + "description": "Limits the search results to any items that are owned\nby the given list of owners, defined as a list of comma separated\nuser IDs.\n\nThe 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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "123422", + "23532", + "3241212" + ], + "explode": false + }, + { + "name": "recent_updater_user_ids", + "in": "query", + "description": "Limits the search results to any items that have been updated\nby the given list of users, defined as a list of comma separated\nuser IDs.\n\nThe 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\nThis feature only searches back to the last 10 versions of an item.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "123422", + "23532", + "3241212" + ], + "explode": false + }, + { + "name": "ancestor_folder_ids", + "in": "query", + "description": "Limits the search results to items within the given\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\nThe 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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "4535234", + "234123235", + "2654345" + ], + "explode": false + }, + { + "name": "content_types", + "in": "query", + "description": "Limits the search results to any items that match the search query\nfor a specific part of the file, for example the file description.\n\nContent types are defined as a comma separated lists\nof Box recognized content types. The allowed content types are as follows.\n\n* `name` - The name of the item, as defined by its `name` field.\n* `description` - The description of the item, as defined by its\n `description` field.\n* `file_content` - The actual content of the file.\n* `comments` - The content of any of the comments on a file or\n folder.\n* `tags` - Any tags that are applied to an item, as defined by its\n `tags` field.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "name", + "description", + "file_content", + "comments", + "tag" + ] + } + }, + "example": [ + "name", + "description" + ], + "explode": false + }, + { + "name": "type", + "in": "query", + "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", + "required": false, + "schema": { + "type": "string", + "enum": [ + "file", + "folder", + "web_link" + ] + }, + "example": "file" + }, + { + "name": "trash_content", + "in": "query", + "description": "Determines if the search should look in the trash for items.\n\nBy default, this API only returns search results for items\nnot currently in the trash (`non_trashed_only`).\n\n* `trashed_only` - Only searches for items currently in the trash\n* `non_trashed_only` - Only searches for items currently not in\n the trash\n* `all_items` - Searches for both trashed and non-trashed items.", + "required": false, + "schema": { + "type": "string", + "default": "non_trashed_only", + "enum": [ + "non_trashed_only", + "trashed_only", + "all_items" + ] + }, + "example": "non_trashed_only" + }, + { + "name": "mdfilters", + "in": "query", + "description": "Limits the search results to any items for which the metadata matches the provided filter.\nThis parameter is a list that specifies exactly **one** metadata template used to filter the search results. \nThe parameter is required unless the `query` parameter is provided.", + "required": false, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MetadataFilter" + }, + "maxItems": 1, + "minItems": 1 + }, + "example": [ + { + "scope": "enterprise", + "templateKey": "contract", + "filters": [ + { + "category": "online" + }, + { + "contractValue": 100000 + } + ] + } + ] + }, + { + "name": "sort", + "in": "query", + "description": "Defines the order in which search results are returned. This API\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.", + "required": false, + "schema": { + "type": "string", + "default": "relevance", + "enum": [ + "modified_at", + "relevance" + ] + }, + "example": "modified_at" + }, + { + "name": "direction", + "in": "query", + "description": "Defines the direction in which search results are ordered. This API\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.", + "required": false, + "schema": { + "type": "string", + "default": "DESC", + "enum": [ + "DESC", + "ASC" + ] + }, + "example": "ASC" + }, + { + "name": "limit", + "in": "query", + "description": "Defines the maximum number of items to return as part of a page of\nresults.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 30, + "maximum": 200 + }, + "example": 100 + }, + { + "name": "include_recent_shared_links", + "in": "query", + "description": "Defines whether the search results should include any items\nthat the user recently accessed through a shared link.\n\nWhen 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)", + "required": false, + "schema": { + "type": "boolean", + "default": false + }, + "example": true + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + }, + { + "name": "deleted_user_ids", + "in": "query", + "description": "Limits the search results to items that were deleted by the given\nlist of users, defined as a list of comma separated user IDs.\n\nThe `trash_content` parameter needs to be set to `trashed_only`.\n\nIf searching in trash is not performed, an empty result set\nis returned. The items need to be owned or shared with\nthe currently authenticated user for them to show up in the search\nresults.\n\nIf the user does not have access to any files owned by\nany of the users, an empty result set is returned.\n\nData available from 2023-02-01 onwards.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "123422", + "23532", + "3241212" + ] + }, + { + "name": "deleted_at_range", + "in": "query", + "description": "Limits the search results to any items deleted within a given\ndate range.\n\nDate ranges are defined as comma separated RFC3339 timestamps.\n\nIf the the start date is omitted (`2014-05-17T13:35:01-07:00`),\nanything deleted before the end date will be returned.\n\nIf the end date is omitted (`2014-05-15T13:35:01-07:00`),\nthe current date will be used as the end date instead.\n\nThe `trash_content` parameter needs to be set to `trashed_only`.\n\nIf searching in trash is not performed, then an empty result\nis returned.\n\nData available from 2023-02-01 onwards.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "2014-05-15T13:35:01-07:00", + "2014-05-17T13:35:01-07:00" + ] + } + ], + "responses": { + "200": { + "description": "Returns a collection of search results. If there are no matching\nsearch results, the `entries` array will be empty.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/SearchResults" + }, + { + "$ref": "#/components/schemas/SearchResultsWithSharedLinks" + } + ] + } + } + } + }, + "400": { + "description": "Returns an error when the request was not valid. This can have multiple\nreasons and the `context_info` object will provide you with more details.\n\n* `missing_parameter` - Please provide at least the `query` or `mdfilters`\n query parameter in a search.\n* `invalid_parameter` - Any of the fields might not be in the right\n format. This could for example mean that one of the RFC3339 dates is\n incorrect, or a string is provided where an integer is expected.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error when the user does not have the permission to make\nthis API call.\n\n* The developer provided a `scope` of `enterprise_content` but did\n not request this scope to be enabled for the user through our\n support channels.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the user does not have access to an item\nmentioned in the request.\n\n* The developer provided a folder ID in `ancestor_folder_ids`\n that either does not exist or the user does not have access to.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "search", + "tags": [ + "Search" + ] + } + }, + "/tasks": { + "post": { + "operationId": "post_tasks", + "summary": "Create task", + "description": "Creates a single task on a file. This task is not assigned to any user and\nwill need to be assigned separately.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "item": { + "description": "The file to attach the task to.", + "type": "object", + "properties": { + "id": { + "description": "The ID of the file", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`file`", + "type": "string", + "example": "file", + "enum": [ + "file" + ] + } + } + }, + "action": { + "description": "The action the task assignee will be prompted to do. Must be\n\n* `review` defines an approval task that can be approved or\nrejected\n* `complete` defines a general task which can be completed", + "type": "string", + "example": "review", + "default": "review", + "enum": [ + "review", + "complete" + ] + }, + "message": { + "description": "An optional message to include with the task.", + "type": "string", + "example": "Please review", + "default": "" + }, + "due_at": { + "description": "Defines when the task is due. Defaults to `null` if not\nprovided.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "completion_rule": { + "description": "Defines which assignees need to complete this task before the task\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.", + "type": "string", + "example": "all_assignees", + "default": "all_assignees", + "enum": [ + "all_assignees", + "any_assignee" + ] + } + }, + "required": [ + "item" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns the newly created task.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Task" + } + } + } + }, + "400": { + "description": "Returned if the request parameters or body is not valid.\n\n* `bad_request` when the body does not contain a valid request. This may\nbe because the `action` or `completion_rule` are not one of the allowed\nvalues.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error when the user does not have the permission to create a\ntask on the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the file could not be found or the user does not\nhave access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "tasks", + "tags": [ + "Tasks" + ] + } + }, + "/tasks/{task_id}": { + "get": { + "operationId": "get_tasks_id", + "summary": "Get task", + "description": "Retrieves information about a specific task.", + "parameters": [ + { + "name": "task_id", + "in": "path", + "description": "The ID of the task.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "200": { + "description": "Returns a task object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Task" + } + } + } + }, + "404": { + "description": "Returns an error when the task could not be found or the user does not\nhave access to the file the task is assigned to.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "tasks", + "tags": [ + "Tasks" + ] + }, + "put": { + "operationId": "put_tasks_id", + "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", + "in": "path", + "description": "The ID of the task.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "action": { + "description": "The action the task assignee will be prompted to do. Must be\n\n* `review` defines an approval task that can be approved or\nrejected\n* `complete` defines a general task which can be completed", + "type": "string", + "example": "review", + "enum": [ + "review", + "complete" + ] + }, + "message": { + "description": "The message included with the task.", + "type": "string", + "example": "Please review" + }, + "due_at": { + "description": "When the task is due at.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "completion_rule": { + "description": "Defines which assignees need to complete this task before the task\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.", + "type": "string", + "example": "all_assignees", + "enum": [ + "all_assignees", + "any_assignee" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated task object", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Task" + } + } + } + }, + "400": { + "description": "Returned if the request parameters or body is not valid.\n\n* `bad_request` when the body does not contain a valid request. This may\nbe because the `action` or `completion_rule` are not one of the allowed\nvalues.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error when the user does not have the permission to update a\ntask on the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the file could not be found or the user does not\nhave access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "tasks", + "tags": [ + "Tasks" + ] + }, + "delete": { + "operationId": "delete_tasks_id", + "summary": "Remove task", + "description": "Removes a task from a file.", + "parameters": [ + { + "name": "task_id", + "in": "path", + "description": "The ID of the task.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the task was successfully deleted." + }, + "404": { + "description": "Returns an error when the task could not be found or the user does not\nhave access to the file the task is assigned to.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "tasks", + "tags": [ + "Tasks" + ] + } + }, + "/tasks/{task_id}/assignments": { + "get": { + "operationId": "get_tasks_id_assignments", + "summary": "List task assignments", + "description": "Lists all of the assignments for a given task.", + "parameters": [ + { + "name": "task_id", + "in": "path", + "description": "The ID of the task.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "200": { + "description": "Returns a collection of task assignment defining what task on\na file has been assigned to which users and by who.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TaskAssignments" + } + } + } + }, + "404": { + "description": "Returns an error when the task could not be found or the user does not\nhave access to the file the task is assigned to.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "500": { + "description": "Returns an error if the task assignment ID was omitted in\nthe request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "task_assignments", + "tags": [ + "Task assignments" + ] + } + }, + "/task_assignments": { + "post": { + "operationId": "post_task_assignments", + "summary": "Assign task", + "description": "Assigns a task to a user.\n\nA task can be assigned to more than one user by creating multiple\nassignments.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "task": { + "description": "The task to assign to a user.", + "type": "object", + "properties": { + "id": { + "description": "The ID of the task", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type of the item to assign.", + "type": "string", + "example": "task", + "enum": [ + "task" + ] + } + }, + "required": [ + "id", + "type" + ] + }, + "assign_to": { + "description": "The user to assign the task to.", + "type": "object", + "properties": { + "id": { + "description": "The ID of the user to assign to the\ntask.\n\nTo specify a user by their email\naddress use the `login` parameter.", + "type": "string", + "example": "3242343" + }, + "login": { + "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.", + "type": "string", + "example": "john@example.com" + } + } + } + }, + "required": [ + "task", + "assign_to" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new task assignment object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TaskAssignment" + } + } + } + }, + "403": { + "description": "Returns an error if a change is attempted for a completed task or the user\ndoes not have access to the item linked to the task for the given task\nassignment.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the task cannot be found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "500": { + "description": "Returns an error if any of the IDs for this request were not valid, or if\nthe targeted user does not have access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "task_assignments", + "tags": [ + "Task assignments" + ] + } + }, + "/task_assignments/{task_assignment_id}": { + "get": { + "operationId": "get_task_assignments_id", + "summary": "Get task assignment", + "description": "Retrieves information about a task assignment.", + "parameters": [ + { + "name": "task_assignment_id", + "in": "path", + "description": "The ID of the task assignment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "200": { + "description": "Returns a task assignment, specifying who the task has been assigned to\nand by whom.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TaskAssignment" + } + } + } + }, + "404": { + "description": "Returns an error when the task assignment could not be found or the user\ndoes not have access to the file the task is assigned to.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "task_assignments", + "tags": [ + "Task assignments" + ] + }, + "put": { + "operationId": "put_task_assignments_id", + "summary": "Update task assignment", + "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", + "in": "path", + "description": "The ID of the task assignment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "description": "An optional message by the assignee that can be added to the task.", + "type": "string", + "example": "Looks good to me" + }, + "resolution_state": { + "description": "The state of the task assigned to the user.\n\n* For a task with an `action` value of `complete` this can be\n`incomplete` or `completed`.\n* For a task with an `action` of `review` this can be\n`incomplete`, `approved`, or `rejected`.", + "type": "string", + "example": "completed", + "enum": [ + "completed", + "incomplete", + "approved", + "rejected" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated task assignment object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TaskAssignment" + } + } + } + }, + "400": { + "description": "Returns an error if a resolution state is incompatible with the action\ntype of the task.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the task assignment could not be found or the user\ndoes not have access to the file the task is assigned to.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "task_assignments", + "tags": [ + "Task assignments" + ] + }, + "delete": { + "operationId": "delete_task_assignments_id", + "summary": "Unassign task", + "description": "Deletes a specific task assignment.", + "parameters": [ + { + "name": "task_assignment_id", + "in": "path", + "description": "The ID of the task assignment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the task\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "task_assignments", + "tags": [ + "Task assignments" + ] + } + }, + "/shared_items": { + "get": { + "operationId": "get_shared_items", + "summary": "Find file for shared link", + "description": "Returns the file represented by a shared link.\n\nA shared file can be represented by a shared link,\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.\n\nThe `shared_link_permission_options` array field can be returned\nby requesting it in the `fields` query parameter.", + "parameters": [ + { + "name": "if-none-match", + "in": "header", + "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "boxapi", + "in": "header", + "description": "A header containing the shared link and optional password for the\nshared link.\n\nThe format for this header is as follows.\n\n`shared_link=[link]&shared_link_password=[password]`", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link=[link]&shared_link_password=[password]" + } + ], + "responses": { + "200": { + "description": "Returns a full file resource if the shared link is valid and\nthe user has access to it.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/File--Full" + } + } + } + }, + "304": { + "description": "Returns an empty response when the `If-None-Match` header matches\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_files", + "tags": [ + "Shared links (Files)" + ] + } + }, + "/files/{file_id}#get_shared_link": { + "get": { + "operationId": "get_files_id#get_shared_link", + "summary": "Get shared link for file", + "description": "Gets the information for a shared link on a file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link" + } + ], + "responses": { + "200": { + "description": "Returns the base representation of a file with the\nadditional shared link information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/File--Full" + }, + "examples": { + "default": { + "value": { + "id": "12345", + "type": "file", + "etag": "1", + "shared_link": { + "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", + "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", + "vanity_url": null, + "vanity_name": null, + "effective_access": "open", + "effective_permission": "can_download", + "is_password_enabled": false, + "unshared_at": "2020-09-21T10:34:41-07:00", + "download_count": 0, + "preview_count": 0, + "access": "open", + "permissions": { + "can_preview": true, + "can_download": true, + "can_edit": true + } + } + } + } + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file is not found, or the user does not\nhave access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_files", + "tags": [ + "Shared links (Files)" + ] + } + }, + "/files/{file_id}#add_shared_link": { + "put": { + "operationId": "put_files_id#add_shared_link", + "summary": "Add shared link to file", + "description": "Adds a shared link to a file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "shared_link": { + "description": "The settings for the shared link to create on the file.\nUse an empty object (`{}`) to use the default settings for shared\nlinks.", + "type": "object", + "properties": { + "access": { + "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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ] + }, + "password": { + "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", + "type": "string", + "example": "do-n8t-use-this-Password", + "nullable": true + }, + "vanity_name": { + "description": "Defines a custom vanity name to use in the shared link URL,\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.", + "type": "string", + "example": "my-shared-link", + "minLength": 12 + }, + "unshared_at": { + "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.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "permissions": { + "type": "object", + "properties": { + "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", + "type": "boolean", + "example": true + }, + "can_preview": { + "description": "If the shared link allows for previewing of files.\nThis value is always `true`. For shared links on folders\nthis also applies to any items in the folder.", + "type": "boolean", + "example": true + }, + "can_edit": { + "description": "If the shared link allows for editing of files.\nThis can only be set when `access` is set to\n`open` or `company`.\nThis value can only be `true` is `can_download` is\nalso `true`.", + "type": "boolean", + "example": true + } + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the base representation of a file with a new shared\nlink attached.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/File--Full" + }, + "examples": { + "default": { + "value": { + "id": "12345", + "type": "file", + "etag": "1", + "shared_link": { + "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", + "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", + "vanity_url": null, + "vanity_name": null, + "effective_access": "open", + "effective_permission": "can_download", + "is_password_enabled": false, + "unshared_at": "2020-09-21T10:34:41-07:00", + "download_count": 0, + "preview_count": 0, + "access": "open", + "permissions": { + "can_preview": true, + "can_download": true, + "can_edit": true + } + } + } + } + } + } + } + }, + "400": { + "description": "Returned when there is an incorrect permission combination", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned if the user does not have all the permissions to complete the\nupdate.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file is not found, or the user does not\nhave access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "412": { + "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_files", + "tags": [ + "Shared links (Files)" + ] + } + }, + "/files/{file_id}#update_shared_link": { + "put": { + "operationId": "put_files_id#update_shared_link", + "summary": "Update shared link on file", + "description": "Updates a shared link on a file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "shared_link": { + "description": "The settings for the shared link to update.", + "type": "object", + "properties": { + "access": { + "description": "The level of access for the shared link. This can be\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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ] + }, + "password": { + "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", + "type": "string", + "example": "do-n8t-use-this-Password", + "nullable": true + }, + "vanity_name": { + "description": "Defines a custom vanity name to use in the shared link URL,\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.", + "type": "string", + "example": "my-shared-link", + "minLength": 12 + }, + "unshared_at": { + "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.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "permissions": { + "type": "object", + "properties": { + "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", + "type": "boolean", + "example": true + }, + "can_preview": { + "description": "If the shared link allows for previewing of files.\nThis value is always `true`. For shared links on folders\nthis also applies to any items in the folder.", + "type": "boolean", + "example": true + }, + "can_edit": { + "description": "If the shared link allows for editing of files.\nThis can only be set when `access` is set to\n`open` or `company`.\nThis value can only be `true` is `can_download` is\nalso `true`.", + "type": "boolean", + "example": true + } + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns a basic representation of the file, with the updated shared\nlink attached.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/File--Full" + }, + "examples": { + "default": { + "value": { + "id": "12345", + "type": "file", + "etag": "1", + "shared_link": { + "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", + "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", + "vanity_url": null, + "vanity_name": null, + "effective_access": "open", + "effective_permission": "can_download", + "is_password_enabled": false, + "unshared_at": "2020-09-21T10:34:41-07:00", + "download_count": 0, + "preview_count": 0, + "access": "open", + "permissions": { + "can_preview": true, + "can_download": true, + "can_edit": true + } + } + } + } + } + } + } + }, + "400": { + "description": "Returned when there is an incorrect permission combination", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned if the user does not have all the permissions to complete the\nupdate.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file is not found, or the user does not\nhave access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "412": { + "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_files", + "tags": [ + "Shared links (Files)" + ] + } + }, + "/files/{file_id}#remove_shared_link": { + "put": { + "operationId": "put_files_id#remove_shared_link", + "summary": "Remove shared link from file", + "description": "Removes a shared link from a file.", + "parameters": [ + { + "name": "file_id", + "in": "path", + "description": "The unique identifier that represents a file.\n\nThe ID for any file can be determined\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`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "shared_link": { + "description": "By setting this value to `null`, the shared link\nis removed from the file.", + "type": "object", + "example": null, + "nullable": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns a basic representation of a file, with the shared link removed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/File--Full" + }, + "examples": { + "default": { + "value": { + "id": "12345", + "type": "file", + "etag": "1", + "shared_link": null + } + } + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned if the user does not have all the permissions to complete the\nupdate.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file is not found, or the user does not\nhave access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "412": { + "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_files", + "tags": [ + "Shared links (Files)" + ] + } + }, + "/shared_items#folders": { + "get": { + "operationId": "get_shared_items#folders", + "summary": "Find folder for shared link", + "description": "Return the folder represented by a shared link.\n\nA shared folder can be represented by a shared link,\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", + "in": "header", + "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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "boxapi", + "in": "header", + "description": "A header containing the shared link and optional password for the\nshared link.\n\nThe format for this header is as follows.\n\n`shared_link=[link]&shared_link_password=[password]`", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link=[link]&shared_link_password=[password]" + } + ], + "responses": { + "200": { + "description": "Returns a full folder resource if the shared link is valid and\nthe user has access to it.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Folder--Full" + } + } + } + }, + "304": { + "description": "Returns an empty response when the `If-None-Match` header matches\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_folders", + "tags": [ + "Shared links (Folders)" + ] + } + }, + "/folders/{folder_id}#get_shared_link": { + "get": { + "operationId": "get_folders_id#get_shared_link", + "summary": "Get shared link for folder", + "description": "Gets the information for a shared link on a folder.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link" + } + ], + "responses": { + "200": { + "description": "Returns the base representation of a folder with the\nadditional shared link information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Folder--Full" + }, + "examples": { + "default": { + "value": { + "id": "12345", + "type": "folder", + "etag": "1", + "shared_link": { + "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", + "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", + "vanity_url": null, + "vanity_name": null, + "effective_access": "open", + "effective_permission": "can_download", + "is_password_enabled": false, + "unshared_at": "2020-09-21T10:34:41-07:00", + "download_count": 0, + "preview_count": 0, + "access": "open", + "permissions": { + "can_preview": true, + "can_download": true, + "can_edit": false + } + } + } + } + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `folder_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_folders", + "tags": [ + "Shared links (Folders)" + ] + } + }, + "/folders/{folder_id}#add_shared_link": { + "put": { + "operationId": "put_folders_id#add_shared_link", + "summary": "Add shared link to folder", + "description": "Adds a shared link to a folder.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "shared_link": { + "description": "The settings for the shared link to create on the folder.\n\nUse an empty object (`{}`) to use the default settings for shared\nlinks.", + "type": "object", + "properties": { + "access": { + "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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ] + }, + "password": { + "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", + "type": "string", + "example": "do-n8t-use-this-Password", + "nullable": true + }, + "vanity_name": { + "description": "Defines a custom vanity name to use in the shared link URL,\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.", + "type": "string", + "example": "my-shared-link", + "minLength": 12 + }, + "unshared_at": { + "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.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "permissions": { + "type": "object", + "properties": { + "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", + "type": "boolean", + "example": true + }, + "can_preview": { + "description": "If the shared link allows for previewing of files.\nThis value is always `true`. For shared links on folders\nthis also applies to any items in the folder.", + "type": "boolean", + "example": true + }, + "can_edit": { + "description": "This value can only be `false` for items\nwith a `type` of `folder`.", + "type": "boolean", + "example": false + } + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the base representation of a folder with a new shared\nlink attached.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Folder--Full" + }, + "examples": { + "default": { + "value": { + "id": "12345", + "type": "folder", + "etag": "1", + "shared_link": { + "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", + "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", + "vanity_url": null, + "vanity_name": null, + "effective_access": "open", + "effective_permission": "can_download", + "is_password_enabled": false, + "unshared_at": "2020-09-21T10:34:41-07:00", + "download_count": 0, + "preview_count": 0, + "access": "open", + "permissions": { + "can_preview": true, + "can_download": true, + "can_edit": false + } + } + } + } + } + } + } + }, + "400": { + "description": "Returned when there is an incorrect permission combination", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned if the user does not have all the permissions to complete the\nupdate.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `folder_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "412": { + "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the folder. This indicates that the folder\nhas changed since it was last requested.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_folders", + "tags": [ + "Shared links (Folders)" + ] + } + }, + "/folders/{folder_id}#update_shared_link": { + "put": { + "operationId": "put_folders_id#update_shared_link", + "summary": "Update shared link on folder", + "description": "Updates a shared link on a folder.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "shared_link": { + "description": "The settings for the shared link to update.", + "type": "object", + "properties": { + "access": { + "description": "The level of access for the shared link. This can be\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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ] + }, + "password": { + "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", + "type": "string", + "example": "do-n8t-use-this-Password" + }, + "vanity_name": { + "description": "Defines a custom vanity name to use in the shared link URL,\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.", + "type": "string", + "example": "my-shared-link", + "minLength": 12 + }, + "unshared_at": { + "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.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "permissions": { + "type": "object", + "properties": { + "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", + "type": "boolean", + "example": true + }, + "can_preview": { + "description": "If the shared link allows for previewing of files.\nThis value is always `true`. For shared links on folders\nthis also applies to any items in the folder.", + "type": "boolean", + "example": true + }, + "can_edit": { + "description": "This value can only be `false` for items\nwith a `type` of `folder`.", + "type": "boolean", + "example": false + } + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns a basic representation of the folder, with the updated shared\nlink attached.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Folder--Full" + }, + "examples": { + "default": { + "value": { + "id": "12345", + "type": "folder", + "etag": "1", + "shared_link": { + "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", + "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", + "vanity_url": null, + "vanity_name": null, + "effective_access": "open", + "effective_permission": "can_download", + "is_password_enabled": false, + "unshared_at": "2020-09-21T10:34:41-07:00", + "download_count": 0, + "preview_count": 0, + "access": "open", + "permissions": { + "can_preview": true, + "can_download": true, + "can_edit": false + } + } + } + } + } + } + } + }, + "400": { + "description": "Returned when there is an incorrect permission combination", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned if the user does not have all the permissions to complete the\nupdate.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `folder_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "412": { + "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the folder. This indicates that the folder\nhas changed since it was last requested.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_folders", + "tags": [ + "Shared links (Folders)" + ] + } + }, + "/folders/{folder_id}#remove_shared_link": { + "put": { + "operationId": "put_folders_id#remove_shared_link", + "summary": "Remove shared link from folder", + "description": "Removes a shared link from a folder.", + "parameters": [ + { + "name": "folder_id", + "in": "path", + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "shared_link": { + "description": "By setting this value to `null`, the shared link\nis removed from the folder.", + "type": "object", + "example": null, + "nullable": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns a basic representation of a folder, with the shared link removed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Folder--Full" + }, + "examples": { + "default": { + "value": { + "id": "12345", + "type": "folder", + "etag": "1", + "shared_link": null + } + } + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned if the user does not have all the permissions to complete the\nupdate.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `folder_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "412": { + "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the folder. This indicates that the folder\nhas changed since it was last requested.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_folders", + "tags": [ + "Shared links (Folders)" + ] + } + }, + "/web_links": { + "post": { + "operationId": "post_web_links", + "summary": "Create web link", + "description": "Creates a web link object within a folder.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "url": { + "description": "The URL that this web link links to. Must start with\n`\"http://\"` or `\"https://\"`.", + "type": "string", + "example": "https://box.com" + }, + "parent": { + "description": "The parent folder to create the web link within.", + "type": "object", + "properties": { + "id": { + "description": "The ID of parent folder", + "type": "string", + "example": "0" + } + }, + "required": [ + "id" + ] + }, + "name": { + "description": "Name of the web link. Defaults to the URL if not set.", + "type": "string", + "example": "Box Website" + }, + "description": { + "description": "Description of the web link.", + "type": "string", + "example": "Cloud Content Management" + } + }, + "required": [ + "parent", + "url" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns the newly created web link object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebLink" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "web_links", + "tags": [ + "Web links" + ] + } + }, + "/web_links/{web_link_id}": { + "get": { + "operationId": "get_web_links_id", + "summary": "Get web link", + "description": "Retrieve information about a web link.", + "parameters": [ + { + "name": "web_link_id", + "in": "path", + "description": "The ID of the web link.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "boxapi", + "in": "header", + "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been\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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "shared_link=[link]&shared_link_password=[password]" + } + ], + "responses": { + "200": { + "description": "Returns the web link object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebLink" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "web_links", + "tags": [ + "Web links" + ] + }, + "post": { + "operationId": "post_web_links_id", + "summary": "Restore web link", + "description": "Restores a web link that has been moved to the trash.\n\nAn optional new parent ID can be provided to restore the web link to in case\nthe original folder has been deleted.", + "parameters": [ + { + "name": "web_link_id", + "in": "path", + "description": "The ID of the web link.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "An optional new name for the web link.", + "type": "string", + "example": "Restored.docx" + }, + "parent": { + "allOf": [ + { + "type": "object", + "description": "The parent for this item", + "properties": { + "id": { + "description": "The ID of parent item", + "type": "string", + "example": "123" + } + } + }, + { + "description": "Specifies an optional ID of a folder to restore the web link\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TrashWebLinkRestored" + } + } + } + }, + "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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if the web link is not in the trash.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error if there is an web link with the same name\nin the folder the web link is being restored to.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "trashed_web_links", + "tags": [ + "Trashed web links" + ] + }, + "put": { + "operationId": "put_web_links_id", + "summary": "Update web link", + "description": "Updates a web link object.", + "parameters": [ + { + "name": "web_link_id", + "in": "path", + "description": "The ID of the web link.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "url": { + "description": "The new URL that the web link links to. Must start with\n`\"http://\"` or `\"https://\"`.", + "type": "string", + "example": "https://box.com" + }, + "parent": { + "allOf": [ + { + "type": "object", + "description": "The parent for this item", + "properties": { + "id": { + "description": "The ID of parent item", + "type": "string", + "example": "123" + } + } + }, + { + "description": "The new parent folder to put the web link in.\nUse this to move the web link to a different folder." + } + ] + }, + "name": { + "description": "A new name for the web link. Defaults to the URL if not set.", + "type": "string", + "example": "Box Website" + }, + "description": { + "description": "A new description of the web link.", + "type": "string", + "example": "Cloud Content Management" + }, + "shared_link": { + "description": "The settings for the shared link to update.", + "type": "object", + "properties": { + "access": { + "description": "The level of access for the shared link. This can be\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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ] + }, + "password": { + "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", + "type": "string", + "example": "do-not-use-this-password", + "nullable": true + }, + "vanity_name": { + "description": "Defines a custom vanity name to use in the shared link URL,\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.", + "type": "string", + "example": "my-shared-link", + "minLength": 12 + }, + "unshared_at": { + "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.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated web link object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebLink" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "web_links", + "tags": [ + "Web links" + ] + }, + "delete": { + "operationId": "delete_web_links_id", + "summary": "Remove web link", + "description": "Deletes a web link.", + "parameters": [ + { + "name": "web_link_id", + "in": "path", + "description": "The ID of the web link.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "204": { + "description": "An empty response will be returned when the web link\nwas successfully deleted." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "web_links", + "tags": [ + "Web links" + ] + } + }, + "/web_links/{web_link_id}/trash": { + "get": { + "operationId": "get_web_links_id_trash", + "summary": "Get trashed web link", + "description": "Retrieves a web link that has been moved to the trash.", + "parameters": [ + { + "name": "web_link_id", + "in": "path", + "description": "The ID of the web link.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns the web link that was trashed,\nincluding information about when the it\nwas moved to the trash.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TrashWebLink" + } + } + } + }, + "404": { + "description": "Returns an error if the web link is not in the trash.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "trashed_web_links", + "tags": [ + "Trashed web links" + ] + }, + "delete": { + "operationId": "delete_web_links_id_trash", + "summary": "Permanently remove web link", + "description": "Permanently deletes a web link that is in the trash.\nThis action cannot be undone.", + "parameters": [ + { + "name": "web_link_id", + "in": "path", + "description": "The ID of the web link.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the web link was\npermanently deleted." + }, + "404": { + "description": "Returns an error if the web link is not in the trash.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "trashed_web_links", + "tags": [ + "Trashed web links" + ] + } + }, + "/shared_items#web_links": { + "get": { + "operationId": "get_shared_items#web_links", + "summary": "Find web link for shared link", + "description": "Returns the web link represented by a shared link.\n\nA shared web link can be represented by a shared link,\nwhich can originate within the current enterprise or within another.\n\nThis endpoint allows an application to retrieve information about a\nshared web link when only given a shared link.", + "parameters": [ + { + "name": "if-none-match", + "in": "header", + "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "boxapi", + "in": "header", + "description": "A header containing the shared link and optional password for the\nshared link.\n\nThe format for this header is as follows.\n\n`shared_link=[link]&shared_link_password=[password]`", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link=[link]&shared_link_password=[password]" + } + ], + "responses": { + "200": { + "description": "Returns a full file resource if the shared link is valid and\nthe user has access to it.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebLink" + } + } + } + }, + "304": { + "description": "Returns an empty response when the `If-None-Match` header matches\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_web_links", + "tags": [ + "Shared links (Web Links)" + ] + } + }, + "/web_links/{web_link_id}#get_shared_link": { + "get": { + "operationId": "get_web_links_id#get_shared_link", + "summary": "Get shared link for web link", + "description": "Gets the information for a shared link on a web link.", + "parameters": [ + { + "name": "web_link_id", + "in": "path", + "description": "The ID of the web link.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link" + } + ], + "responses": { + "200": { + "description": "Returns the base representation of a web link with the\nadditional shared link information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebLink" + }, + "examples": { + "default": { + "value": { + "id": "12345", + "type": "web_link", + "etag": "1", + "shared_link": { + "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", + "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", + "vanity_url": null, + "vanity_name": null, + "effective_access": "open", + "effective_permission": "can_download", + "is_password_enabled": false, + "unshared_at": "2020-09-21T10:34:41-07:00", + "download_count": 0, + "preview_count": 0, + "access": "open", + "permissions": { + "can_preview": true, + "can_download": true, + "can_edit": false + } + } + } + } + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file is not found, or the user does not\nhave access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_web_links", + "tags": [ + "Shared links (Web Links)" + ] + } + }, + "/web_links/{web_link_id}#add_shared_link": { + "put": { + "operationId": "put_web_links_id#add_shared_link", + "summary": "Add shared link to web link", + "description": "Adds a shared link to a web link.", + "parameters": [ + { + "name": "web_link_id", + "in": "path", + "description": "The ID of the web link.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "shared_link": { + "description": "The settings for the shared link to create on the web link.\n\nUse an empty object (`{}`) to use the default settings for shared\nlinks.", + "type": "object", + "properties": { + "access": { + "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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ] + }, + "password": { + "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", + "type": "string", + "example": "do-n8t-use-this-Password", + "nullable": true + }, + "vanity_name": { + "description": "Defines a custom vanity name to use in the shared link URL,\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.", + "type": "string", + "example": "my-shared-link", + "minLength": 12 + }, + "unshared_at": { + "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.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "permissions": { + "type": "object", + "properties": { + "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", + "type": "boolean", + "example": true + }, + "can_preview": { + "description": "If the shared link allows for previewing of files.\nThis value is always `true`. For shared links on folders\nthis also applies to any items in the folder.", + "type": "boolean", + "example": true + }, + "can_edit": { + "description": "This value can only be `true` is `type` is `file`.", + "type": "boolean", + "example": false + } + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the base representation of a web link with a new shared\nlink attached.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebLink" + }, + "examples": { + "default": { + "value": { + "id": "12345", + "type": "web_link", + "etag": "1", + "shared_link": { + "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", + "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", + "vanity_url": null, + "vanity_name": null, + "effective_access": "open", + "effective_permission": "can_download", + "is_password_enabled": false, + "unshared_at": "2020-09-21T10:34:41-07:00", + "download_count": 0, + "preview_count": 0, + "access": "open", + "permissions": { + "can_preview": true, + "can_download": true, + "can_edit": false + } + } + } + } + } + } + } + }, + "400": { + "description": "Returned when there is an incorrect permission combination", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned if the user does not have all the permissions to complete the\nupdate.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file is not found, or the user does not\nhave access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "412": { + "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_web_links", + "tags": [ + "Shared links (Web Links)" + ] + } + }, + "/web_links/{web_link_id}#update_shared_link": { + "put": { + "operationId": "put_web_links_id#update_shared_link", + "summary": "Update shared link on web link", + "description": "Updates a shared link on a web link.", + "parameters": [ + { + "name": "web_link_id", + "in": "path", + "description": "The ID of the web link.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "shared_link": { + "description": "The settings for the shared link to update.", + "type": "object", + "properties": { + "access": { + "description": "The level of access for the shared link. This can be\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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ] + }, + "password": { + "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\nPasswords must now be at least eight characters\nlong and include a number, upper case letter, or\na non-numeric or non-alphabetic character.\nA password can only be set when `access` is set to `open`.", + "type": "string", + "example": "do-n8t-use-this-Password", + "nullable": true + }, + "vanity_name": { + "description": "Defines a custom vanity name to use in the shared link URL,\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.", + "type": "string", + "example": "my-shared-link", + "minLength": 12 + }, + "unshared_at": { + "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.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "permissions": { + "type": "object", + "properties": { + "can_download": { + "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`.", + "type": "boolean", + "example": true + }, + "can_preview": { + "description": "If the shared link allows for previewing of files.\nThis value is always `true`. For shared links on folders\nthis also applies to any items in the folder.", + "type": "boolean", + "example": true + }, + "can_edit": { + "description": "This value can only be `true` is `type` is `file`.", + "type": "boolean", + "example": true + } + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns a basic representation of the web link, with the updated shared\nlink attached.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebLink" + }, + "examples": { + "default": { + "value": { + "id": "12345", + "type": "web_link", + "etag": "1", + "shared_link": { + "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", + "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", + "vanity_url": null, + "vanity_name": null, + "effective_access": "open", + "effective_permission": "can_download", + "is_password_enabled": false, + "unshared_at": "2020-09-21T10:34:41-07:00", + "download_count": 0, + "preview_count": 0, + "access": "open", + "permissions": { + "can_preview": true, + "can_download": true, + "can_edit": false + } + } + } + } + } + } + } + }, + "400": { + "description": "Returned when there is an incorrect permission combination", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned if the user does not have all the permissions to complete the\nupdate.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file is not found, or the user does not\nhave access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "412": { + "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_web_links", + "tags": [ + "Shared links (Web Links)" + ] + } + }, + "/web_links/{web_link_id}#remove_shared_link": { + "put": { + "operationId": "put_web_links_id#remove_shared_link", + "summary": "Remove shared link from web link", + "description": "Removes a shared link from a web link.", + "parameters": [ + { + "name": "web_link_id", + "in": "path", + "description": "The ID of the web link.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", + "required": true, + "schema": { + "type": "string" + }, + "example": "shared_link" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "shared_link": { + "description": "By setting this value to `null`, the shared link\nis removed from the web link.", + "type": "object", + "example": null, + "nullable": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns a basic representation of a web link, with the\nshared link removed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebLink" + }, + "examples": { + "default": { + "value": { + "id": "12345", + "type": "web_link", + "etag": "1", + "shared_link": null + } + } + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned if the user does not have all the permissions to complete the\nupdate.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the file is not found, or the user does not\nhave access to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "405": { + "description": "Returned if the `file_id` is not in a recognized format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "412": { + "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shared_links_web_links", + "tags": [ + "Shared links (Web Links)" + ] + } + }, + "/users": { + "get": { + "operationId": "get_users", + "summary": "List enterprise 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", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "john" + }, + { + "name": "user_type", + "in": "query", + "description": "Limits the results to the kind of user specified.\n\n* `all` returns every kind of user for whom the\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.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "all", + "managed", + "external" + ] + }, + "example": "managed" + }, + { + "name": "external_app_user_id", + "in": "query", + "description": "Limits the results to app users with the given\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.", + "required": false, + "schema": { + "type": "string" + }, + "example": "my-user-1234" + }, + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "usemarker", + "in": "query", + "description": "Specifies whether to use marker-based pagination instead of\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.", + "required": false, + "schema": { + "type": "boolean" + }, + "example": true + }, + { + "name": "marker", + "in": "query", + "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`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + } + ], + "responses": { + "200": { + "description": "Returns all of the users in the enterprise.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Users" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "users", + "tags": [ + "Users" + ] + }, + "post": { + "operationId": "post_users", + "summary": "Create user", + "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", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "The name of the user", + "type": "string", + "example": "Aaron Levie", + "maxLength": 50 + }, + "login": { + "description": "The email address the user uses to log in\n\nRequired, unless `is_platform_access_only`\nis set to `true`.", + "type": "string", + "example": "boss@box.com" + }, + "is_platform_access_only": { + "description": "Specifies that the user is an app user.", + "type": "boolean", + "example": true + }, + "role": { + "description": "The user’s enterprise role", + "type": "string", + "example": "user", + "enum": [ + "coadmin", + "user" + ] + }, + "language": { + "description": "The language of the user, formatted in modified version of the\n[ISO 639-1](/guides/api-calls/language-codes) format.", + "type": "string", + "example": "en" + }, + "is_sync_enabled": { + "description": "Whether the user can use Box Sync", + "type": "boolean", + "example": true + }, + "job_title": { + "description": "The user’s job title", + "type": "string", + "example": "CEO", + "maxLength": 100 + }, + "phone": { + "description": "The user’s phone number", + "type": "string", + "example": "6509241374", + "maxLength": 100 + }, + "address": { + "description": "The user’s address", + "type": "string", + "example": "900 Jefferson Ave, Redwood City, CA 94063", + "maxLength": 255 + }, + "space_amount": { + "description": "The user’s total available space in bytes. Set this to `-1` to\nindicate unlimited storage.", + "type": "integer", + "format": "int64", + "example": 11345156112 + }, + "tracking_codes": { + "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.", + "type": "array", + "items": { + "$ref": "#/components/schemas/TrackingCode" + } + }, + "can_see_managed_users": { + "description": "Whether the user can see other enterprise users in their\ncontact list", + "type": "boolean", + "example": true + }, + "timezone": { + "description": "The user's timezone", + "type": "string", + "format": "timezone", + "example": "Africa/Bujumbura" + }, + "is_external_collab_restricted": { + "description": "Whether the user is allowed to collaborate with users outside\ntheir enterprise", + "type": "boolean", + "example": true + }, + "is_exempt_from_device_limits": { + "description": "Whether to exempt the user from enterprise device limits", + "type": "boolean", + "example": true + }, + "is_exempt_from_login_verification": { + "description": "Whether the user must use two-factor authentication", + "type": "boolean", + "example": true + }, + "status": { + "description": "The user's account status", + "type": "string", + "example": "active", + "enum": [ + "active", + "inactive", + "cannot_delete_edit", + "cannot_delete_edit_upload" + ] + }, + "external_app_user_id": { + "description": "An external identifier for an app user, which can be used to look\nup the user. This can be used to tie user IDs from external\nidentity providers to Box users.", + "type": "string", + "example": "my-user-1234" + } + }, + "required": [ + "name" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a user object for the newly created user.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/User--Full" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "users", + "tags": [ + "Users" + ] + } + }, + "/users/me": { + "get": { + "operationId": "get_users_me", + "summary": "Get current user", + "description": "Retrieves information about the user who is currently authenticated.\n\nIn the case of a client-side authenticated OAuth 2.0 application\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", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns a single user object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/User--Full" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "users", + "tags": [ + "Users" + ] + } + }, + "/users/terminate_sessions": { + "post": { + "operationId": "post_users_terminate_sessions", + "summary": "Create jobs to terminate users session", + "description": "Validates the roles and permissions of the user,\nand creates asynchronous jobs\nto terminate the user's sessions.\nReturns the status for the POST request.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "user_ids": { + "description": "A list of user IDs", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "123456", + "456789" + ] + }, + "user_logins": { + "description": "A list of user logins", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "user@sample.com", + "user2@sample.com" + ] + } + }, + "required": [ + "user_ids", + "user_logins" + ] + } + } + } + }, + "responses": { + "202": { + "description": "Returns a message about the request status.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionTerminationMessage" + } + } + } + }, + "400": { + "description": "Returns an error if some of the parameters are\n not valid.\n\n * `Users can not be NULL or EMPTY` when no value is provided\n * `User id format is string` when the provided user id format\n is incorrect\n * `Supported payload format is JSON` when the provided payload\n format is incorrect", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error if there are insufficient permissions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if the resource could not be found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "429": { + "description": "Returns an error if the rate limit is exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "500": { + "description": "Returns an error if there is an internal server issue.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "503": { + "description": "Returns an error if the request timed out.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "session_termination", + "tags": [ + "Session termination" + ] + } + }, + "/users/{user_id}": { + "get": { + "operationId": "get_users_id", + "summary": "Get user", + "description": "Retrieves information about a user in the enterprise.\n\nThe application and the authenticated user need to\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", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns a single user object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields using the [fields](#get-users-id--request--fields)\nparameter.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/User--Full" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "users", + "tags": [ + "Users" + ] + }, + "put": { + "operationId": "put_users_id", + "summary": "Update user", + "description": "Updates a managed or app user in an enterprise. This endpoint\nis only available to users and applications with the right\nadmin permissions.", + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "enterprise": { + "description": "Set this to `null` to roll the user out of the enterprise\nand make them a free user", + "type": "string", + "example": null, + "nullable": true + }, + "notify": { + "description": "Whether the user should receive an email when they\nare rolled out of an enterprise", + "type": "boolean", + "example": true + }, + "name": { + "description": "The name of the user", + "type": "string", + "example": "Aaron Levie", + "maxLength": 50 + }, + "login": { + "description": "The email address the user uses to log in\n\nNote: If the target user's email is not confirmed, then the\nprimary login address cannot be changed.", + "type": "string", + "example": "somename@box.com" + }, + "role": { + "description": "The user’s enterprise role", + "type": "string", + "example": "user", + "enum": [ + "coadmin", + "user" + ] + }, + "language": { + "description": "The language of the user, formatted in modified version of the\n[ISO 639-1](/guides/api-calls/language-codes) format.", + "type": "string", + "example": "en" + }, + "is_sync_enabled": { + "description": "Whether the user can use Box Sync", + "type": "boolean", + "example": true + }, + "job_title": { + "description": "The user’s job title", + "type": "string", + "example": "CEO", + "maxLength": 100 + }, + "phone": { + "description": "The user’s phone number", + "type": "string", + "example": "6509241374", + "maxLength": 100 + }, + "address": { + "description": "The user’s address", + "type": "string", + "example": "900 Jefferson Ave, Redwood City, CA 94063", + "maxLength": 255 + }, + "tracking_codes": { + "description": "Tracking codes allow an admin to generate reports from the\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.", + "type": "array", + "items": { + "$ref": "#/components/schemas/TrackingCode" + } + }, + "can_see_managed_users": { + "description": "Whether the user can see other enterprise users in their\ncontact list", + "type": "boolean", + "example": true + }, + "timezone": { + "description": "The user's timezone", + "type": "string", + "format": "timezone", + "example": "Africa/Bujumbura" + }, + "is_external_collab_restricted": { + "description": "Whether the user is allowed to collaborate with users outside\ntheir enterprise", + "type": "boolean", + "example": true + }, + "is_exempt_from_device_limits": { + "description": "Whether to exempt the user from enterprise device limits", + "type": "boolean", + "example": true + }, + "is_exempt_from_login_verification": { + "description": "Whether the user must use two-factor authentication", + "type": "boolean", + "example": true + }, + "is_password_reset_required": { + "description": "Whether the user is required to reset their password", + "type": "boolean", + "example": true + }, + "status": { + "description": "The user's account status", + "type": "string", + "example": "active", + "enum": [ + "active", + "inactive", + "cannot_delete_edit", + "cannot_delete_edit_upload" + ] + }, + "space_amount": { + "description": "The user’s total available space in bytes. Set this to `-1` to\nindicate unlimited storage.", + "type": "integer", + "format": "int64", + "example": 11345156112 + }, + "notification_email": { + "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.", + "type": "object", + "nullable": true, + "properties": { + "email": { + "description": "The email address to send the notifications to.", + "type": "string", + "example": "notifications@example.com" + } + } + }, + "external_app_user_id": { + "description": "An external identifier for an app user, which can be used to look\nup the user. This can be used to tie user IDs from external\nidentity providers to Box users.\n\nNote: In order to update this field, you need to request a token\nusing the application that created the app user.", + "type": "string", + "example": "my-user-1234" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated user object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/User--Full" + } + } + } + }, + "400": { + "description": "Returns an error if some of the parameters are missing or\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error if the user is not allowed to make the changes.\n\n* `access_denied_insufficient_permissions` when the user does not have\n the right permissions, for example when updating the notification email\n is turned off for the enterprise.\n* `denied_by_policy` when the user does not have the right permissions\n due to the information barrier restrictions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "users", + "tags": [ + "Users" + ] + }, + "delete": { + "operationId": "delete_users_id", + "summary": "Delete user", + "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", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "notify", + "in": "query", + "description": "Whether the user will receive email notification of\nthe deletion", + "schema": { + "type": "boolean" + }, + "example": true + }, + { + "name": "force", + "in": "query", + "description": "Whether the user should be deleted even if this user\nstill own files", + "schema": { + "type": "boolean" + }, + "example": true + } + ], + "responses": { + "204": { + "description": "Removes the user and returns an empty response." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "users", + "tags": [ + "Users" + ] + } + }, + "/users/{user_id}/avatar": { + "get": { + "operationId": "get_users_id_avatar", + "summary": "Get user avatar", + "description": "Retrieves an image of a the user's avatar.", + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "200": { + "description": "When an avatar can be found for the user the\nimage data will be returned in the body of the\nresponse.", + "content": { + "image/jpg": { + "schema": { + "description": "The avatar", + "type": "string", + "format": "binary" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "avatars", + "tags": [ + "User avatars" + ] + }, + "post": { + "operationId": "post_users_id_avatar", + "summary": "Add or update user avatar", + "description": "Adds or updates a user avatar.", + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "pic": { + "description": "The image file to be uploaded to Box.\nAccepted file extensions are `.jpg` or `.png`.\nThe maximum file size is 1MB.", + "type": "string", + "format": "binary" + } + }, + "required": [ + "pic" + ] + } + } + } + }, + "responses": { + "200": { + "description": "* `ok`: Returns the `pic_urls` object with URLs to existing\nuser avatars that were updated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserAvatar" + } + } + } + }, + "201": { + "description": "* `created`: Returns the `pic_urls` object with URLS to user avatars\nuploaded to Box with the request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserAvatar" + } + } + } + }, + "400": { + "description": "* `bad_request`: Returns an error when:\n * An image is not included in the request\n * The uploaded file is empty\n * The image size exceeds 1024 * 1024 pixels\n or 1MB\n * The file extension is other than `.jpg` or `.png`.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "* `forbidden`: Returns an error if the user does not have permissions\nnecessary to upload an avatar or is not activated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "* `not_found`: Returns an error if the user\ndoes not exist or cannot be found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "avatars", + "tags": [ + "User avatars" + ] + }, + "delete": { + "operationId": "delete_users_id_avatar", + "summary": "Delete user avatar", + "description": "Removes an existing user avatar.\nYou cannot reverse this operation.", + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "204": { + "description": "* `no_content`: Removes the avatar and returns an empty response." + }, + "403": { + "description": "* `forbidden`: Returned if the user does not have necessary permissions\n or is not activated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "* `not_found`: Returned if the user or user avatar does not exist\n or cannot be found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "avatars", + "tags": [ + "User avatars" + ] + } + }, + "/users/{user_id}/folders/0": { + "put": { + "operationId": "put_users_id_folders_0", + "summary": "Transfer owned folders", + "description": "Move all of the items (files, folders and workflows) owned by a user into\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", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "notify", + "in": "query", + "description": "Determines if users should receive email notification\nfor the action performed.", + "required": false, + "schema": { + "type": "boolean" + }, + "example": true + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "owned_by": { + "description": "The user who the folder will be transferred to", + "type": "object", + "properties": { + "id": { + "description": "The ID of the user who the folder will be\ntransferred to", + "type": "string", + "example": "1232234" + } + }, + "required": [ + "id" + ] + } + }, + "required": [ + "owned_by" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns the information for the newly created\ndestination folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Folder--Full" + } + } + } + }, + "403": { + "description": "Returns an error when folder ownership cannot be\ntransferred to another user.\n\n* `forbidden_by_policy`: Returned if ownership transfer\n is forbidden due to information barrier restrictions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "transfer", + "tags": [ + "Transfer folders" + ] + } + }, + "/users/{user_id}/email_aliases": { + "get": { + "operationId": "get_users_id_email_aliases", + "summary": "List user's email aliases", + "description": "Retrieves all email aliases for a user. The collection\ndoes not include the primary login for the user.", + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "responses": { + "200": { + "description": "Returns a collection of email aliases.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmailAliases" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "email_aliases", + "tags": [ + "Email aliases" + ] + }, + "post": { + "operationId": "post_users_id_email_aliases", + "summary": "Create email alias", + "description": "Adds a new email alias to a user account..", + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "email": { + "description": "The email address to add to the account as an alias.\n\nNote: The domain of the email alias needs to be registered\n to your enterprise.\nSee the [domain verification guide](\n https://support.box.com/hc/en-us/articles/4408619650579-Domain-Verification\n ) for steps to add a new domain.", + "type": "string", + "example": "alias@example.com" + } + }, + "required": [ + "email" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns the newly created email alias object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmailAlias" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "email_aliases", + "tags": [ + "Email aliases" + ] + } + }, + "/users/{user_id}/email_aliases/{email_alias_id}": { + "delete": { + "operationId": "delete_users_id_email_aliases_id", + "summary": "Remove email alias", + "description": "Removes an email alias from a user.", + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "email_alias_id", + "in": "path", + "description": "The ID of the email alias.", + "required": true, + "schema": { + "type": "string" + }, + "example": "23432" + } + ], + "responses": { + "204": { + "description": "Removes the alias and returns an empty response." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "email_aliases", + "tags": [ + "Email aliases" + ] + } + }, + "/users/{user_id}/memberships": { + "get": { + "operationId": "get_users_id_memberships", + "summary": "List user's groups", + "description": "Retrieves all the groups for a user. Only members of this\ngroup or users with admin-level permissions will be able to\nuse this API.", + "parameters": [ + { + "name": "user_id", + "in": "path", + "description": "The ID of the user.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a collection of membership objects. If there are no\nmemberships, an empty collection will be returned.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupMemberships" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "memberships", + "tags": [ + "Group memberships" + ] + } + }, + "/invites": { + "post": { + "operationId": "post_invites", + "summary": "Create user invite", + "description": "Invites an existing external user to join an enterprise.\n\nThe existing user can not be part of another enterprise and\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", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "enterprise": { + "description": "The enterprise to invite the user to", + "type": "object", + "properties": { + "id": { + "description": "The ID of the enterprise", + "type": "string", + "example": "1232234" + } + }, + "required": [ + "id" + ] + }, + "actionable_by": { + "description": "The user to invite", + "type": "object", + "properties": { + "login": { + "description": "The login of the invited user", + "type": "string", + "example": "john@example.com" + } + }, + "required": [ + "id" + ] + } + }, + "required": [ + "enterprise", + "actionable_by" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns a new invite object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Invite" + } + } + } + }, + "404": { + "description": "Returns `not_found` when user was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "invites", + "tags": [ + "Invites" + ] + } + }, + "/invites/{invite_id}": { + "get": { + "operationId": "get_invites_id", + "summary": "Get user invite status", + "description": "Returns the status of a user invite.", + "parameters": [ + { + "name": "invite_id", + "in": "path", + "description": "The ID of an invite.", + "required": true, + "schema": { + "type": "string" + }, + "example": "213723" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns an invite object", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Invite" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "invites", + "tags": [ + "Invites" + ] + } + }, + "/groups": { + "get": { + "operationId": "get_groups", + "summary": "List groups for enterprise", + "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", + "in": "query", + "description": "Limits the results to only groups whose `name` starts\nwith the search term.", + "required": false, + "schema": { + "type": "string" + }, + "example": "Engineering" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a collection of group objects. If there are no groups, an\nempty collection will be returned.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Groups" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "groups", + "tags": [ + "Groups" + ] + }, + "post": { + "operationId": "post_groups", + "summary": "Create group", + "description": "Creates a new group of users in an enterprise. Only users with admin\npermissions can create new groups.", + "parameters": [ + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "The name of the new group to be created. This name must be unique\nwithin the enterprise.", + "type": "string", + "example": "Customer Support" + }, + "provenance": { + "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.", + "type": "string", + "example": "Active Directory", + "maxLength": 255 + }, + "external_sync_identifier": { + "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.", + "type": "string", + "example": "AD:123456" + }, + "description": { + "description": "A human readable description of the group.", + "type": "string", + "example": "\"Customer Support Group - as imported from Active Directory\"", + "maxLength": 255 + }, + "invitability_level": { + "description": "Specifies who can invite the group to collaborate\non folders.\n\nWhen set to `admins_only` the enterprise admin, co-admins,\nand the group's admin can invite the group.\n\nWhen set to `admins_and_members` all the admins listed\nabove and group members can invite the group.\n\nWhen set to `all_managed_users` all managed users in the\nenterprise can invite the group.", + "type": "string", + "example": "admins_only", + "enum": [ + "admins_only", + "admins_and_members", + "all_managed_users" + ] + }, + "member_viewability_level": { + "description": "Specifies who can see the members of the group.\n\n* `admins_only` - the enterprise admin, co-admins, group's\n group admin\n* `admins_and_members` - all admins and group members\n* `all_managed_users` - all managed users in the\n enterprise", + "type": "string", + "example": "admins_only", + "enum": [ + "admins_only", + "admins_and_members", + "all_managed_users" + ] + } + }, + "required": [ + "name" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns the new group object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Group--Full" + } + } + } + }, + "409": { + "description": "Returns an error a conflict is stopping the group from being created.\n\n* `invalid_parameter`: Often returned if the group name is not unique in\nthe enterprise.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "groups", + "tags": [ + "Groups" + ] + } + }, + "/groups/terminate_sessions": { + "post": { + "operationId": "post_groups_terminate_sessions", + "summary": "Create jobs to terminate user group session", + "description": "Validates the roles and permissions of the group,\nand creates asynchronous jobs\nto terminate the group's sessions.\nReturns the status for the POST request.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "group_ids": { + "description": "A list of group IDs", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "123456", + "456789" + ] + } + }, + "required": [ + "group_ids" + ] + } + } + } + }, + "responses": { + "202": { + "description": "Returns a message about the request status.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionTerminationMessage" + } + } + } + }, + "400": { + "description": "Returns an error if some of the parameters are\nnot valid.\n\n* `Groups can not be NULL or EMPTY` when no value is provided\n* `group id format is string` when the provided group id format\nis incorrect\n* `Supported payload format is JSON` when the provided payload\nformat is incorrect", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error if there are insufficient permissions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if the resource could not be found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "429": { + "description": "Returns an error if the request limit is exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "500": { + "description": "Returns an error if there is an internal server issue.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "503": { + "description": "Returns an error if the request timed out.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "session_termination", + "tags": [ + "Session termination" + ] + } + }, + "/groups/{group_id}": { + "get": { + "operationId": "get_groups_id", + "summary": "Get group", + "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", + "in": "path", + "description": "The ID of the group.", + "required": true, + "schema": { + "type": "string" + }, + "example": "57645" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns the group object", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Group--Full" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "groups", + "tags": [ + "Groups" + ] + }, + "put": { + "operationId": "put_groups_id", + "summary": "Update group", + "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", + "in": "path", + "description": "The ID of the group.", + "required": true, + "schema": { + "type": "string" + }, + "example": "57645" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "description": "The name of the new group to be created. Must be unique within the\nenterprise.", + "type": "string", + "example": "Customer Support" + }, + "provenance": { + "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.", + "type": "string", + "example": "Active Directory", + "maxLength": 255 + }, + "external_sync_identifier": { + "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.", + "type": "string", + "example": "AD:123456" + }, + "description": { + "description": "A human readable description of the group.", + "type": "string", + "example": "\"Customer Support Group - as imported from Active Directory\"", + "maxLength": 255 + }, + "invitability_level": { + "description": "Specifies who can invite the group to collaborate\non folders.\n\nWhen set to `admins_only` the enterprise admin, co-admins,\nand the group's admin can invite the group.\n\nWhen set to `admins_and_members` all the admins listed\nabove and group members can invite the group.\n\nWhen set to `all_managed_users` all managed users in the\nenterprise can invite the group.", + "type": "string", + "example": "admins_only", + "enum": [ + "admins_only", + "admins_and_members", + "all_managed_users" + ] + }, + "member_viewability_level": { + "description": "Specifies who can see the members of the group.\n\n* `admins_only` - the enterprise admin, co-admins, group's\n group admin\n* `admins_and_members` - all admins and group members\n* `all_managed_users` - all managed users in the\n enterprise", + "type": "string", + "example": "admins_only", + "enum": [ + "admins_only", + "admins_and_members", + "all_managed_users" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated group object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Group--Full" + } + } + } + }, + "409": { + "description": "Returns an error a conflict is stopping the group from being created.\n\n* `invalid_parameter`: Often returned if the group name is not unique in\nthe enterprise.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "groups", + "tags": [ + "Groups" + ] + }, + "delete": { + "operationId": "delete_groups_id", + "summary": "Remove group", + "description": "Permanently deletes a group. Only users with\nadmin-level permissions will be able to use this API.", + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the group.", + "required": true, + "schema": { + "type": "string" + }, + "example": "57645" + } + ], + "responses": { + "204": { + "description": "A blank response is returned if the group was\nsuccessfully deleted." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "groups", + "tags": [ + "Groups" + ] + } + }, + "/groups/{group_id}/memberships": { + "get": { + "operationId": "get_groups_id_memberships", + "summary": "List members of group", + "description": "Retrieves all the members for a group. Only members of this\ngroup or users with admin-level permissions will be able to\nuse this API.", + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the group.", + "required": true, + "schema": { + "type": "string" + }, + "example": "57645" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a collection of membership objects. If there are no\nmemberships, an empty collection will be returned.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupMemberships" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "memberships", + "tags": [ + "Group memberships" + ] + } + }, + "/groups/{group_id}/collaborations": { + "get": { + "operationId": "get_groups_id_collaborations", + "summary": "List group collaborations", + "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", + "in": "path", + "description": "The ID of the group.", + "required": true, + "schema": { + "type": "string" + }, + "example": "57645" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a collection of collaboration objects. If there are no\ncollaborations, an empty collection will be returned.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Collaborations" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "list_collaborations", + "tags": [ + "Collaborations (List)" + ] + } + }, + "/group_memberships": { + "post": { + "operationId": "post_group_memberships", + "summary": "Add user to group", + "description": "Creates a group membership. Only users with\nadmin-level permissions will be able to use this API.", + "parameters": [ + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "user": { + "description": "The user to add to the group.", + "type": "object", + "properties": { + "id": { + "description": "The ID of the user to add to the group", + "type": "string", + "example": "1434325" + } + }, + "required": [ + "id" + ] + }, + "group": { + "description": "The group to add the user to.", + "type": "object", + "properties": { + "id": { + "description": "The ID of the group to add the user to", + "type": "string", + "example": "4545523" + } + }, + "required": [ + "id" + ] + }, + "role": { + "description": "The role of the user in the group.", + "type": "string", + "example": "member", + "enum": [ + "member", + "admin" + ] + }, + "configurable_permissions": { + "description": "Custom configuration for the permissions an admin\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.", + "type": "object", + "example": { + "can_run_reports": true + }, + "additionalProperties": { + "type": "boolean", + "description": "A key value pair of custom permissions.", + "example": true, + "x-box-example-key": "can_run_reports" + }, + "nullable": true + } + }, + "required": [ + "user", + "group" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new group membership object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupMembership" + } + } + } + }, + "403": { + "description": "Returns an error when the user cannot be added\nto a group.\n\n* `forbidden_by_policy`: Adding a user\nto a group is forbidden due to information\nbarrier restrictions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "memberships", + "tags": [ + "Group memberships" + ] + } + }, + "/group_memberships/{group_membership_id}": { + "get": { + "operationId": "get_group_memberships_id", + "summary": "Get group membership", + "description": "Retrieves a specific group membership. Only admins of this\ngroup or users with admin-level permissions will be able to\nuse this API.", + "parameters": [ + { + "name": "group_membership_id", + "in": "path", + "description": "The ID of the group membership.", + "required": true, + "schema": { + "type": "string" + }, + "example": "434534" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns the group membership object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupMembership" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "memberships", + "tags": [ + "Group memberships" + ] + }, + "put": { + "operationId": "put_group_memberships_id", + "summary": "Update group membership", + "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", + "in": "path", + "description": "The ID of the group membership.", + "required": true, + "schema": { + "type": "string" + }, + "example": "434534" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "role": { + "description": "The role of the user in the group.", + "type": "string", + "example": "member", + "enum": [ + "member", + "admin" + ] + }, + "configurable_permissions": { + "description": "Custom configuration for the permissions an admin\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.", + "type": "object", + "example": { + "can_run_reports": true + }, + "additionalProperties": { + "type": "boolean", + "description": "A key value pair of custom permissions.", + "example": true, + "x-box-example-key": "can_run_reports" + }, + "nullable": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns a new group membership object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GroupMembership" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "memberships", + "tags": [ + "Group memberships" + ] + }, + "delete": { + "operationId": "delete_group_memberships_id", + "summary": "Remove user from group", + "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", + "in": "path", + "description": "The ID of the group membership.", + "required": true, + "schema": { + "type": "string" + }, + "example": "434534" + } + ], + "responses": { + "204": { + "description": "A blank response is returned if the membership was\nsuccessfully deleted." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "memberships", + "tags": [ + "Group memberships" + ] + } + }, + "/webhooks": { + "get": { + "operationId": "get_webhooks", + "summary": "List all webhooks", + "description": "Returns all defined webhooks for the requesting application.\n\nThis API only returns webhooks that are applied to files or folders that are\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", + "in": "query", + "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`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a list of webhooks.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Webhooks" + } + } + } + }, + "403": { + "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "webhooks", + "tags": [ + "Webhooks" + ] + }, + "post": { + "operationId": "post_webhooks", + "summary": "Create webhook", + "description": "Creates a webhook.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "target": { + "description": "The item that will trigger the webhook", + "type": "object", + "properties": { + "id": { + "description": "The ID of the item to trigger a webhook", + "type": "string", + "example": "1231232" + }, + "type": { + "description": "The type of item to trigger a webhook", + "type": "string", + "example": "file", + "enum": [ + "file", + "folder" + ] + } + } + }, + "address": { + "description": "The URL that is notified by this webhook", + "type": "string", + "example": "https://example.com/webhooks" + }, + "triggers": { + "description": "An array of event names that this webhook is\nto be triggered for", + "type": "array", + "items": { + "title": "Webhook Trigger", + "example": "FILE.UPLOADED", + "type": "string", + "description": "The event name that triggered this webhook", + "enum": [ + "FILE.UPLOADED", + "FILE.PREVIEWED", + "FILE.DOWNLOADED", + "FILE.TRASHED", + "FILE.DELETED", + "FILE.RESTORED", + "FILE.COPIED", + "FILE.MOVED", + "FILE.LOCKED", + "FILE.UNLOCKED", + "FILE.RENAMED", + "COMMENT.CREATED", + "COMMENT.UPDATED", + "COMMENT.DELETED", + "TASK_ASSIGNMENT.CREATED", + "TASK_ASSIGNMENT.UPDATED", + "METADATA_INSTANCE.CREATED", + "METADATA_INSTANCE.UPDATED", + "METADATA_INSTANCE.DELETED", + "FOLDER.CREATED", + "FOLDER.RENAMED", + "FOLDER.DOWNLOADED", + "FOLDER.RESTORED", + "FOLDER.DELETED", + "FOLDER.COPIED", + "FOLDER.MOVED", + "FOLDER.TRASHED", + "WEBHOOK.DELETED", + "COLLABORATION.CREATED", + "COLLABORATION.ACCEPTED", + "COLLABORATION.REJECTED", + "COLLABORATION.REMOVED", + "COLLABORATION.UPDATED", + "SHARED_LINK.DELETED", + "SHARED_LINK.CREATED", + "SHARED_LINK.UPDATED", + "SIGN_REQUEST.COMPLETED", + "SIGN_REQUEST.DECLINED", + "SIGN_REQUEST.EXPIRED", + "SIGN_REQUEST.SIGNER_EMAIL_BOUNCED" + ] + }, + "example": [ + "FILE.UPLOADED" + ] + } + }, + "required": [ + "target", + "triggers", + "address" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns the new webhook object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Webhook" + } + } + } + }, + "400": { + "description": "Returns an error if the parameters were\nincorrect.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if the target item could\nnot be found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error if the a webhook for this\ncombination of target, application, and user\nalready exists.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "webhooks", + "tags": [ + "Webhooks" + ] + } + }, + "/webhooks/{webhook_id}": { + "get": { + "operationId": "get_webhooks_id", + "summary": "Get webhook", + "description": "Retrieves a specific webhook", + "parameters": [ + { + "name": "webhook_id", + "in": "path", + "description": "The ID of the webhook.", + "required": true, + "schema": { + "type": "string" + }, + "example": "3321123" + } + ], + "responses": { + "200": { + "description": "Returns a webhook object", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Webhook" + } + } + } + }, + "403": { + "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if the webhook could not be found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "webhooks", + "tags": [ + "Webhooks" + ] + }, + "put": { + "operationId": "put_webhooks_id", + "summary": "Update webhook", + "description": "Updates a webhook.", + "parameters": [ + { + "name": "webhook_id", + "in": "path", + "description": "The ID of the webhook.", + "required": true, + "schema": { + "type": "string" + }, + "example": "3321123" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "target": { + "description": "The item that will trigger the webhook", + "type": "object", + "properties": { + "id": { + "description": "The ID of the item to trigger a webhook", + "type": "string", + "example": "1231232" + }, + "type": { + "description": "The type of item to trigger a webhook", + "type": "string", + "example": "file", + "enum": [ + "file", + "folder" + ] + } + } + }, + "address": { + "description": "The URL that is notified by this webhook", + "type": "string", + "example": "https://example.com/webhooks" + }, + "triggers": { + "description": "An array of event names that this webhook is\nto be triggered for", + "type": "array", + "items": { + "title": "Webhook Trigger", + "example": "FILE.UPLOADED", + "type": "string", + "description": "The event name that triggered this webhook", + "enum": [ + "FILE.UPLOADED", + "FILE.PREVIEWED", + "FILE.DOWNLOADED", + "FILE.TRASHED", + "FILE.DELETED", + "FILE.RESTORED", + "FILE.COPIED", + "FILE.MOVED", + "FILE.LOCKED", + "FILE.UNLOCKED", + "FILE.RENAMED", + "COMMENT.CREATED", + "COMMENT.UPDATED", + "COMMENT.DELETED", + "TASK_ASSIGNMENT.CREATED", + "TASK_ASSIGNMENT.UPDATED", + "METADATA_INSTANCE.CREATED", + "METADATA_INSTANCE.UPDATED", + "METADATA_INSTANCE.DELETED", + "FOLDER.CREATED", + "FOLDER.RENAMED", + "FOLDER.DOWNLOADED", + "FOLDER.RESTORED", + "FOLDER.DELETED", + "FOLDER.COPIED", + "FOLDER.MOVED", + "FOLDER.TRASHED", + "WEBHOOK.DELETED", + "COLLABORATION.CREATED", + "COLLABORATION.ACCEPTED", + "COLLABORATION.REJECTED", + "COLLABORATION.REMOVED", + "COLLABORATION.UPDATED", + "SHARED_LINK.DELETED", + "SHARED_LINK.CREATED", + "SHARED_LINK.UPDATED", + "SIGN_REQUEST.COMPLETED", + "SIGN_REQUEST.DECLINED", + "SIGN_REQUEST.EXPIRED", + "SIGN_REQUEST.SIGNER_EMAIL_BOUNCED" + ] + }, + "example": [ + "FILE.UPLOADED" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the new webhook object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Webhook" + } + } + } + }, + "400": { + "description": "Returns an error if the parameters were\nincorrect.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if the target item or webhook\ncould not be found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error if the a webhook for this\ncombination of target, application, and user\nalready exists.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "webhooks", + "tags": [ + "Webhooks" + ] + }, + "delete": { + "operationId": "delete_webhooks_id", + "summary": "Remove webhook", + "description": "Deletes a webhook.", + "parameters": [ + { + "name": "webhook_id", + "in": "path", + "description": "The ID of the webhook.", + "required": true, + "schema": { + "type": "string" + }, + "example": "3321123" + } + ], + "responses": { + "204": { + "description": "An empty response will be returned when the webhook\nwas successfully deleted." + }, + "403": { + "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if the webhook could not be found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "webhooks", + "tags": [ + "Webhooks" + ] + } + }, + "/skill_invocations/{skill_id}": { + "put": { + "operationId": "put_skill_invocations_id", + "summary": "Update all Box Skill cards on file", + "description": "An alternative method that can be used to overwrite and update all Box Skill\nmetadata cards on a file.", + "parameters": [ + { + "name": "skill_id", + "in": "path", + "description": "The ID of the skill to apply this metadata for.", + "required": true, + "schema": { + "type": "string" + }, + "example": "33243242" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "description": "Defines the status of this invocation. Set this to `success` when setting Skill cards.", + "type": "string", + "example": "success", + "enum": [ + "invoked", + "processing", + "success", + "transient_failure", + "permanent_failure" + ] + }, + "metadata": { + "description": "The metadata to set for this skill. This is a list of\nBox Skills cards. These cards will overwrite any existing Box\nskill cards on the file.", + "type": "object", + "properties": { + "cards": { + "description": "A list of Box Skill cards to apply to this file.", + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/KeywordSkillCard" + }, + { + "$ref": "#/components/schemas/TimelineSkillCard" + }, + { + "$ref": "#/components/schemas/TranscriptSkillCard" + }, + { + "$ref": "#/components/schemas/StatusSkillCard" + } + ] + } + } + } + }, + "file": { + "description": "The file to assign the cards to.", + "type": "object", + "properties": { + "type": { + "description": "`file`", + "type": "string", + "example": "file", + "enum": [ + "file" + ] + }, + "id": { + "description": "The ID of the file", + "type": "string", + "example": "3243244" + } + } + }, + "file_version": { + "description": "The optional file version to assign the cards to.", + "type": "object", + "properties": { + "type": { + "description": "`file_version`", + "type": "string", + "example": "file_version", + "enum": [ + "file_version" + ] + }, + "id": { + "description": "The ID of the file version", + "type": "string", + "example": "731381601045" + } + } + }, + "usage": { + "description": "A descriptor that defines what items are affected by this call.\n\nSet this to the default values when setting a card to a `success`\nstate, and leave it out in most other situations.", + "type": "object", + "properties": { + "unit": { + "description": "`file`", + "type": "string", + "example": "file" + }, + "value": { + "description": "`1`", + "type": "number", + "example": 1 + } + } + } + }, + "required": [ + "status", + "metadata", + "file" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns an empty response when the card has been successfully updated." + }, + "400": { + "description": "Returns an error when the request body is not valid.\n\n* `schema_validation_failed` - The request body contains a value for\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the file could not be found or the user does not\nhave access.\n\n* `not_found` - The file could not be found, or the user does not have\naccess to the file.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "skills", + "tags": [ + "Skills" + ] + } + }, + "/events": { + "options": { + "operationId": "options_events", + "summary": "Get events long poll endpoint", + "tags": [ + "Events" + ], + "x-box-tag": "events", + "description": "Returns a list of real-time servers that can be used for long-polling updates\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RealtimeServers" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + } + }, + "get": { + "operationId": "get_events", + "summary": "List user and enterprise 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 events\nfor the entire enterprise, set the `stream_type` to `admin_logs_streaming`\nfor live monitoring of new events, or `admin_logs` for querying across\nhistorical events. The user making the API call will\nneed to have admin privileges, and the application will need to have the\nscope `manage enterprise properties` checked.", + "parameters": [ + { + "name": "stream_type", + "in": "query", + "description": "Defines the type of events that are returned\n\n* `all` returns everything for a user and is the default\n* `changes` returns events that may cause file tree changes\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. This\n stream type is for programmatically pulling from a 1 year history of\n events across all users within the enterprise and within a\n `created_after` and `created_before` time frame. The complete history\n of events will be returned in chronological order based on the event\n time, but latency will be much higher than `admin_logs_streaming`.\n* `admin_logs_streaming` returns all events for an entire enterprise and\n requires the user making the API call to have admin permissions. This\n stream type is for polling for recent events across all users within\n the enterprise. Latency will be much lower than `admin_logs`, but\n events will not be returned in chronological order and may\n contain duplicates.", + "schema": { + "type": "string", + "default": "all", + "enum": [ + "all", + "changes", + "sync", + "admin_logs", + "admin_logs_streaming" + ] + }, + "example": "all" + }, + { + "name": "stream_position", + "in": "query", + "description": "The location in the event stream to start receiving events from.\n\n* `now` will return an empty list events and\nthe latest stream position for initialization.\n* `0` or `null` will return all events.", + "schema": { + "type": "string" + }, + "example": "1348790499819" + }, + { + "name": "limit", + "in": "query", + "description": "Limits the number of events returned\n\nNote: Sometimes, the events less than the limit requested can be returned\neven when there may be more events remaining. This is primarily done in\nthe case where a number of events have already been retrieved and these\nretrieved events are returned rather than delaying for an unknown amount\nof time to see if there are any more results.", + "schema": { + "type": "integer", + "format": "int64", + "default": 100, + "maximum": 500 + }, + "example": 50 + }, + { + "name": "event_type", + "in": "query", + "description": "A comma-separated list of events to filter by. This can only be used when\nrequesting the events with a `stream_type` of `admin_logs` or\n`adming_logs_streaming`. For any other `stream_type` this value will be\nignored.", + "schema": { + "type": "array", + "items": { + "type": "string", + "description": "An event type that can be filtered by", + "enum": [ + "ACCESS_GRANTED", + "ACCESS_REVOKED", + "ADD_DEVICE_ASSOCIATION", + "ADD_LOGIN_ACTIVITY_DEVICE", + "ADMIN_LOGIN", + "APPLICATION_CREATED", + "APPLICATION_PUBLIC_KEY_ADDED", + "APPLICATION_PUBLIC_KEY_DELETED", + "CHANGE_ADMIN_ROLE", + "CHANGE_FOLDER_PERMISSION", + "COLLABORATION_ACCEPT", + "COLLABORATION_EXPIRATION", + "COLLABORATION_INVITE", + "COLLABORATION_REMOVE", + "COLLABORATION_ROLE_CHANGE", + "COMMENT_CREATE", + "COMMENT_DELETE", + "CONTENT_WORKFLOW_ABNORMAL_DOWNLOAD_ACTIVITY", + "CONTENT_WORKFLOW_AUTOMATION_ADD", + "CONTENT_WORKFLOW_AUTOMATION_DELETE", + "CONTENT_WORKFLOW_POLICY_ADD", + "CONTENT_WORKFLOW_SHARING_POLICY_VIOLATION", + "CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION", + "COPY", + "DATA_RETENTION_CREATE_RETENTION", + "DATA_RETENTION_REMOVE_RETENTION", + "DELETE", + "DELETE_USER", + "DEVICE_TRUST_CHECK_FAILED", + "DOWNLOAD", + "EDIT", + "EDIT_USER", + "EMAIL_ALIAS_CONFIRM", + "EMAIL_ALIAS_REMOVE", + "ENTERPRISE_APP_AUTHORIZATION_UPDATE", + "EXTERNAL_COLLAB_SECURITY_SETTINGS", + "FAILED_LOGIN", + "FILE_MARKED_MALICIOUS", + "FILE_WATERMARKED_DOWNLOAD", + "GROUP_ADD_ITEM", + "GROUP_ADD_USER", + "GROUP_CREATION", + "GROUP_DELETION", + "GROUP_EDITED", + "GROUP_REMOVE_ITEM", + "GROUP_REMOVE_USER", + "ITEM_EMAIL_SEND", + "ITEM_MODIFY", + "ITEM_OPEN", + "ITEM_SHARED_UPDATE", + "ITEM_SYNC", + "ITEM_UNSYNC", + "LEGAL_HOLD_ASSIGNMENT_CREATE", + "LEGAL_HOLD_ASSIGNMENT_DELETE", + "LEGAL_HOLD_POLICY_CREATE", + "LEGAL_HOLD_POLICY_DELETE", + "LEGAL_HOLD_POLICY_UPDATE", + "LOCK", + "LOGIN", + "METADATA_INSTANCE_CREATE", + "METADATA_INSTANCE_DELETE", + "METADATA_INSTANCE_UPDATE", + "METADATA_TEMPLATE_CREATE", + "METADATA_TEMPLATE_DELETE", + "METADATA_TEMPLATE_UPDATE", + "MOVE", + "NEW_USER", + "OAUTH2_ACCESS_TOKEN_REVOKE", + "PREVIEW", + "REMOVE_DEVICE_ASSOCIATION", + "REMOVE_LOGIN_ACTIVITY_DEVICE", + "RENAME", + "RETENTION_POLICY_ASSIGNMENT_ADD", + "SHARE", + "SHARED_LINK_SEND", + "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", + "SHIELD_SHARED_LINK_ACCESS_BLOCKED", + "SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_CREATE", + "SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_UPDATE", + "SIGN_DOCUMENT_ASSIGNED", + "SIGN_DOCUMENT_CANCELLED", + "SIGN_DOCUMENT_COMPLETED", + "SIGN_DOCUMENT_CONVERTED", + "SIGN_DOCUMENT_CREATED", + "SIGN_DOCUMENT_DECLINED", + "SIGN_DOCUMENT_EXPIRED", + "SIGN_DOCUMENT_SIGNED", + "SIGN_DOCUMENT_VIEWED_BY_SIGNED", + "SIGNER_DOWNLOADED", + "SIGNER_FORWARDED", + "STORAGE_EXPIRATION", + "TASK_ASSIGNMENT_CREATE", + "TASK_ASSIGNMENT_DELETE", + "TASK_ASSIGNMENT_UPDATE", + "TASK_CREATE", + "TASK_UPDATE", + "TERMS_OF_SERVICE_ACCEPT", + "TERMS_OF_SERVICE_REJECT", + "UNDELETE", + "UNLOCK", + "UNSHARE", + "UPDATE_COLLABORATION_EXPIRATION", + "UPDATE_SHARE_EXPIRATION", + "UPLOAD", + "USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE", + "WATERMARK_LABEL_CREATE", + "WATERMARK_LABEL_DELETE" + ] + } + }, + "example": [ + "ACCESS_GRANTED" + ], + "explode": false + }, + { + "name": "created_after", + "in": "query", + "description": "The lower bound date and time to return events for. This can only be used\nwhen requesting the events with a `stream_type` of `admin_logs`. For any\nother `stream_type` this value will be ignored.", + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2012-12-12T10:53:43-08:00" + }, + { + "name": "created_before", + "in": "query", + "description": "The upper bound date and time to return events for. This can only be used\nwhen requesting the events with a `stream_type` of `admin_logs`. For any\nother `stream_type` this value will be ignored.", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + }, + "example": "2013-12-12T10:53:43-08:00" + } + ], + "responses": { + "200": { + "description": "Returns a list of event objects.\n\nEvents objects are returned in pages, with each page (chunk)\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Events" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "events", + "tags": [ + "Events" + ] + } + }, + "/collections": { + "get": { + "operationId": "get_collections", + "summary": "List all collections", + "description": "Retrieves all collections for a given user.\n\nCurrently, only the `favorites` collection\nis supported.", + "parameters": [ + { + "name": "fields", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns all collections for the given user", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Collections" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "collections", + "tags": [ + "Collections" + ] + } + }, + "/collections/{collection_id}/items": { + "get": { + "operationId": "get_collections_id_items", + "summary": "List collection items", + "description": "Retrieves the files and/or folders contained within\nthis collection.", + "parameters": [ + { + "name": "collection_id", + "in": "path", + "description": "The ID of the collection.", + "required": true, + "schema": { + "type": "string" + }, + "example": "926489" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "offset", + "in": "query", + "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "default": 0 + }, + "example": 1000 + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns an array of items in the collection.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Items" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "collections", + "tags": [ + "Collections" + ] + } + }, + "/recent_items": { + "get": { + "operationId": "get_recent_items", + "summary": "List recently accessed 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", + "in": "query", + "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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + } + ], + "responses": { + "200": { + "description": "Returns a list recent items access by a user.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RecentItems" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "recent_items", + "tags": [ + "Recent items" + ] + } + }, + "/retention_policies": { + "get": { + "operationId": "get_retention_policies", + "summary": "List retention policies", + "description": "Retrieves all of the retention policies for an enterprise.", + "parameters": [ + { + "name": "policy_name", + "in": "query", + "description": "Filters results by a case sensitive prefix of the name of\nretention policies.", + "required": false, + "schema": { + "type": "string" + }, + "example": "Sales Policy" + }, + { + "name": "policy_type", + "in": "query", + "description": "Filters results by the type of retention policy.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "finite", + "indefinite" + ] + }, + "example": "finite" + }, + { + "name": "created_by_user_id", + "in": "query", + "description": "Filters results by the ID of the user who created policy.", + "required": false, + "schema": { + "type": "string" + }, + "example": "21312321" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + } + ], + "responses": { + "200": { + "description": "Returns a list retention policies in the enterprise.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetentionPolicies" + } + } + } + }, + "400": { + "description": "Returns a `bad_request` if a non existent `policy_type` was specified.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if the user specified in `created_by_user_id`\ndoes not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "retention_policies", + "tags": [ + "Retention policies" + ] + }, + "post": { + "operationId": "post_retention_policies", + "summary": "Create retention policy", + "description": "Creates a retention policy.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "policy_name": { + "description": "The name for the retention policy", + "type": "string", + "example": "Some Policy Name" + }, + "description": { + "description": "The additional text description of the retention policy.", + "type": "string", + "example": "Policy to retain all reports for at least one month" + }, + "policy_type": { + "description": "The type of the retention policy. A retention\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.", + "type": "string", + "example": "finite", + "enum": [ + "finite", + "indefinite" + ] + }, + "disposition_action": { + "description": "The disposition action of the retention policy.\n`permanently_delete` deletes the content\nretained by the policy permanently.\n`remove_retention` lifts retention policy\nfrom the content, allowing it to be deleted\nby users once the retention policy has expired.", + "type": "string", + "example": "permanently_delete", + "enum": [ + "permanently_delete", + "remove_retention" + ] + }, + "retention_length": { + "description": "The length of the retention policy. This value\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`.", + "example": "365", + "oneOf": [ + { + "type": "string", + "format": "int32", + "nullable": true + }, + { + "type": "number", + "format": "int32", + "nullable": false + } + ] + }, + "retention_type": { + "description": "Specifies the retention type:\n\n* `modifiable`: You can modify the retention policy. For example,\nyou can add or remove folders, shorten or lengthen\nthe policy duration, or delete the assignment.\nUse this type if your retention policy\nis not related to any regulatory purposes.\n\n* `non_modifiable`: You can modify the retention policy\nonly in a limited way: add a folder, lengthen the duration,\nretire the policy, change the disposition action\nor notification settings. You cannot perform other actions,\nsuch as deleting the assignment or shortening the\npolicy duration. Use this type to ensure\ncompliance with regulatory retention policies.", + "type": "string", + "example": "modifiable", + "enum": [ + "modifiable", + "non_modifiable" + ] + }, + "can_owner_extend_retention": { + "description": "Whether the owner of a file will be allowed to\nextend the retention.", + "type": "boolean", + "example": true, + "enum": [ + true, + false + ] + }, + "are_owners_notified": { + "description": "Whether owner and co-owners of a file are notified\nwhen the policy nears expiration.", + "type": "boolean", + "example": true, + "enum": [ + true, + false + ] + }, + "custom_notification_recipients": { + "description": "A list of users notified when\nthe retention policy duration is about to end.", + "type": "array", + "items": { + "$ref": "#/components/schemas/User--Mini" + } + } + }, + "required": [ + "policy_name", + "policy_type", + "disposition_action" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new retention policy object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetentionPolicy" + } + } + } + }, + "400": { + "description": "Returns a `bad_request` error with the `retention_length` was\nspecified for a `infinite` retention policy, an incorrect\n`disposition_action` was set, or description exceeds maximum length of\n500 characters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error if a retention policy with the given name already exists", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "retention_policies", + "tags": [ + "Retention policies" + ] + } + }, + "/retention_policies/{retention_policy_id}": { + "get": { + "operationId": "get_retention_policies_id", + "summary": "Get retention policy", + "description": "Retrieves a retention policy.", + "parameters": [ + { + "name": "retention_policy_id", + "in": "path", + "description": "The ID of the retention policy.", + "required": true, + "schema": { + "type": "string" + }, + "example": "982312" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns the retention policy object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetentionPolicy" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "retention_policies", + "tags": [ + "Retention policies" + ] + }, + "put": { + "operationId": "put_retention_policies_id", + "summary": "Update retention policy", + "description": "Updates a retention policy.", + "parameters": [ + { + "name": "retention_policy_id", + "in": "path", + "description": "The ID of the retention policy.", + "required": true, + "schema": { + "type": "string" + }, + "example": "982312" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "policy_name": { + "description": "The name for the retention policy", + "type": "string", + "example": "Some Policy Name", + "nullable": true + }, + "description": { + "description": "The additional text description of the retention policy.", + "type": "string", + "example": "Policy to retain all reports for at least one month", + "nullable": true + }, + "disposition_action": { + "description": "The disposition action of the retention policy.\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.\nYou can use `null` if you don't want to change `disposition_action`.", + "example": "permanently_delete", + "anyOf": [ + { + "type": "string", + "enum": [ + "permanently_delete", + "remove_retention" + ] + }, + { + "type": "string", + "pattern": ".^", + "nullable": true + } + ] + }, + "retention_type": { + "description": "Specifies the retention type:\n\n* `modifiable`: You can modify the retention policy. For example,\nyou can add or remove folders, shorten or lengthen\nthe policy duration, or delete the assignment.\nUse this type if your retention policy\nis not related to any regulatory purposes.\n* `non-modifiable`: You can modify the retention policy\nonly in a limited way: add a folder, lengthen the duration,\nretire the policy, change the disposition action\nor notification settings. You cannot perform other actions,\nsuch as deleting the assignment or shortening the\npolicy duration. Use this type to ensure\ncompliance with regulatory retention policies.\n\nWhen updating a retention policy, you can use\n`non-modifiable` type only. You can convert a\n`modifiable` policy to `non-modifiable`, but\nnot the other way around.", + "type": "string", + "example": "non-modifiable", + "nullable": true + }, + "retention_length": { + "description": "The length of the retention policy. This value\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`.", + "example": "365", + "oneOf": [ + { + "type": "string", + "format": "int32", + "nullable": true + }, + { + "type": "number", + "format": "int32", + "nullable": false + } + ] + }, + "status": { + "description": "Used to retire a retention policy.\n\nIf not retiring a policy, do not include this parameter\nor set it to `null`.", + "type": "string", + "example": "retired", + "nullable": true + }, + "can_owner_extend_retention": { + "description": "Determines if the owner of items under the policy\ncan extend the retention when the original retention\nduration is about to end.", + "type": "boolean", + "example": false, + "nullable": true + }, + "are_owners_notified": { + "description": "Determines if owners and co-owners of items\nunder the policy are notified when\nthe retention duration is about to end.", + "type": "boolean", + "example": false, + "nullable": true + }, + "custom_notification_recipients": { + "description": "A list of users notified when the retention duration is about to end.", + "type": "array", + "items": { + "$ref": "#/components/schemas/User--Base" + }, + "nullable": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated retention policy object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetentionPolicy" + } + } + } + }, + "400": { + "description": "Returns a `bad_request` if an incorrect\n`disposition_action` was set or description exceeds maximum length of\n500 characters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error when a user wants to\nshorten the duration of a\nnon-modifiable policy, or to convert\na non-modifiable policy to\na modifiable one.\nNote: Lengthening policy duration\nis allowed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error if a retention policy with the given name already exists", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "retention_policies", + "tags": [ + "Retention policies" + ] + }, + "delete": { + "operationId": "delete_retention_policies_id", + "summary": "Delete retention policy", + "description": "Permanently deletes a retention policy.", + "parameters": [ + { + "name": "retention_policy_id", + "in": "path", + "description": "The ID of the retention policy.", + "required": true, + "schema": { + "type": "string" + }, + "example": "982312" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the policy has been deleted." + }, + "403": { + "description": "Returns an error if the policy is non-modifiable or the user does\nnot have the required access to perform the action.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if the policy is not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "retention_policies", + "tags": [ + "Retention policies" + ] + } + }, + "/retention_policies/{retention_policy_id}/assignments": { + "get": { + "operationId": "get_retention_policies_id_assignments", + "summary": "List retention policy assignments", + "description": "Returns a list of all retention policy assignments associated with a specified\nretention policy.", + "parameters": [ + { + "name": "retention_policy_id", + "in": "path", + "description": "The ID of the retention policy.", + "required": true, + "schema": { + "type": "string" + }, + "example": "982312" + }, + { + "name": "type", + "in": "query", + "description": "The type of the retention policy assignment to retrieve.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "folder", + "enterprise", + "metadata_template" + ] + }, + "example": "metadata_template" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a list of the retention policy assignments associated with the\nspecified retention policy.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetentionPolicyAssignments" + } + } + } + }, + "400": { + "description": "Returns an error if an unknown `type` is specified.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "retention_policy_assignments", + "tags": [ + "Retention policy assignments" + ] + } + }, + "/retention_policy_assignments": { + "post": { + "operationId": "post_retention_policy_assignments", + "summary": "Assign retention policy", + "description": "Assigns a retention policy to an item.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "policy_id": { + "description": "The ID of the retention policy to assign", + "type": "string", + "example": "173463" + }, + "assign_to": { + "description": "The item to assign the policy to", + "type": "object", + "properties": { + "type": { + "description": "The type of item to assign the policy to.", + "type": "string", + "example": "metadata_template", + "enum": [ + "enterprise", + "folder", + "metadata_template" + ] + }, + "id": { + "description": "The ID of item to assign the policy to.\nSet to `null` or omit when `type` is set to\n`enterprise`.", + "type": "string", + "example": "6564564", + "nullable": true + } + }, + "required": [ + "type" + ] + }, + "filter_fields": { + "description": "If the `assign_to` type is `metadata_template`,\nthen optionally add the `filter_fields` parameter which will\nrequire an array of objects with a field entry and a value entry.\nCurrently only one object of `field` and `value` is supported.", + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "description": "The metadata attribute key id.", + "type": "string", + "example": "a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4" + }, + "value": { + "description": "The metadata attribute field id. For value, only\nenum and multiselect types are supported.", + "type": "string", + "example": "0c27b756-0p87-4fe0-a43a-59fb661ccc4e" + } + } + } + }, + "start_date_field": { + "description": "The date the retention policy assignment begins.\n\nIf the `assigned_to` type is `metadata_template`,\nthis field can be a date field's metadata attribute key id.", + "type": "string", + "example": "upload_date" + } + }, + "required": [ + "policy_id", + "assign_to" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new retention policy assignment object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetentionPolicyAssignment" + } + } + } + }, + "400": { + "description": "Returns an error if an `id` is specified while assigning the\nretention policy to an enterprise.\n\nReturns an error if `start_date_field` is present but `assign_to.type`\nis not `metadata_template`\n\nReturns an error if `start_date_field` is present, but belongs to a\ndifferent metadata template than the one specified in `assign_to.id`\n\nReturns an error if `start_date_field` is present, but the\n`retention_policy` has a `retention_length` of \"indefinite\"\n\nReturns an error if `start_date_field` is present, but cannot be resolved\nto a valid metadata date field.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if no retention policy with the given `policy_id` exists.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error if a retention policy of equal or greater length has\nalready been assigned to this item.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "retention_policy_assignments", + "tags": [ + "Retention policy assignments" + ] + } + }, + "/retention_policy_assignments/{retention_policy_assignment_id}": { + "get": { + "operationId": "get_retention_policy_assignments_id", + "summary": "Get retention policy assignment", + "description": "Retrieves a retention policy assignment", + "parameters": [ + { + "name": "retention_policy_assignment_id", + "in": "path", + "description": "The ID of the retention policy assignment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "1233123" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns the retention policy assignment object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetentionPolicyAssignment" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "retention_policy_assignments", + "tags": [ + "Retention policy assignments" + ] + }, + "delete": { + "operationId": "delete_retention_policy_assignments_id", + "summary": "Remove retention policy assignment", + "description": "Removes a retention policy assignment\napplied to content.", + "parameters": [ + { + "name": "retention_policy_assignment_id", + "in": "path", + "description": "The ID of the retention policy assignment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "1233123" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the policy assignment\nis successfully deleted." + }, + "403": { + "description": "Returns an error when the assignment relates to\na retention policy that cannot be modified.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error when the retention policy\nassignment does not exist.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "retention_policy_assignments", + "tags": [ + "Retention policy assignments" + ] + } + }, + "/retention_policy_assignments/{retention_policy_assignment_id}/files_under_retention": { + "get": { + "operationId": "get_retention_policy_assignments_id_files_under_retention", + "summary": "Get files under retention", + "description": "Returns a list of files under retention for a retention policy assignment.", + "parameters": [ + { + "name": "retention_policy_assignment_id", + "in": "path", + "description": "The ID of the retention policy assignment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "1233123" + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a list of files under retention that are associated with the\nspecified retention policy assignment.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FilesUnderRetention" + } + } + } + }, + "400": { + "description": "Returns an error if `retention_policy_assignment_id` is not specified.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "retention_policy_assignments", + "tags": [ + "Retention policy assignments" + ] + } + }, + "/retention_policy_assignments/{retention_policy_assignment_id}/file_versions_under_retention": { + "get": { + "operationId": "get_retention_policy_assignments_id_file_versions_under_retention", + "summary": "Get file versions under retention", + "description": "Returns a list of file versions under retention for a retention policy\nassignment.", + "parameters": [ + { + "name": "retention_policy_assignment_id", + "in": "path", + "description": "The ID of the retention policy assignment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "1233123" + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a list of file versions under retention that are associated with\nthe specified retention policy assignment.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FilesUnderRetention" + } + } + } + }, + "400": { + "description": "Returns an error if `retention_policy_assignment_id` is not specified.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "retention_policy_assignments", + "tags": [ + "Retention policy assignments" + ] + } + }, + "/legal_hold_policies": { + "get": { + "operationId": "get_legal_hold_policies", + "summary": "List all legal hold policies", + "description": "Retrieves a list of legal hold policies that belong to\nan enterprise.", + "parameters": [ + { + "name": "policy_name", + "in": "query", + "description": "Limits results to policies for which the names start with\nthis search term. This is a case-insensitive prefix.", + "required": false, + "schema": { + "type": "string" + }, + "example": "Sales Policy" + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a list of legal hold policies.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LegalHoldPolicies" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "legal_hold_policies", + "tags": [ + "Legal hold policies" + ] + }, + "post": { + "operationId": "post_legal_hold_policies", + "summary": "Create legal hold policy", + "description": "Create a new legal hold policy.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "policy_name": { + "description": "The name of the policy.", + "type": "string", + "example": "Sales Policy", + "maxLength": 254 + }, + "description": { + "description": "A description for the policy.", + "type": "string", + "example": "A custom policy for the sales team", + "maxLength": 500 + }, + "filter_started_at": { + "description": "The filter start date.\n\nWhen this policy is applied using a `custodian` legal\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", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "maxLength": 500 + }, + "filter_ended_at": { + "description": "The filter end date.\n\nWhen this policy is applied using a `custodian` legal\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", + "format": "date-time", + "example": "2012-12-18T10:53:43-08:00", + "maxLength": 500 + }, + "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", + "example": true + } + }, + "required": [ + "policy_name" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new legal hold policy object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LegalHoldPolicy" + } + } + } + }, + "400": { + "description": "Returns an error if required parameters are missing,\nor neither `is_ongoing` or filter dates are specified.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error if a policy with this name already exists.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "legal_hold_policies", + "tags": [ + "Legal hold policies" + ] + } + }, + "/legal_hold_policies/{legal_hold_policy_id}": { + "get": { + "operationId": "get_legal_hold_policies_id", + "summary": "Get legal hold policy", + "description": "Retrieve a legal hold policy.", + "parameters": [ + { + "name": "legal_hold_policy_id", + "in": "path", + "description": "The ID of the legal hold policy", + "required": true, + "schema": { + "type": "string" + }, + "example": "324432" + } + ], + "responses": { + "200": { + "description": "Returns a legal hold policy object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LegalHoldPolicy" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "legal_hold_policies", + "tags": [ + "Legal hold policies" + ] + }, + "put": { + "operationId": "put_legal_hold_policies_id", + "summary": "Update legal hold policy", + "description": "Update legal hold policy.", + "parameters": [ + { + "name": "legal_hold_policy_id", + "in": "path", + "description": "The ID of the legal hold policy", + "required": true, + "schema": { + "type": "string" + }, + "example": "324432" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "policy_name": { + "description": "The name of the policy.", + "type": "string", + "example": "Sales Policy", + "maxLength": 254 + }, + "description": { + "description": "A description for the policy.", + "type": "string", + "example": "A custom policy for the sales team", + "maxLength": 500 + }, + "release_notes": { + "description": "Notes around why the policy was released.", + "type": "string", + "example": "Required for GDPR", + "maxLength": 500 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns a new legal hold policy object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LegalHoldPolicy" + } + } + } + }, + "409": { + "description": "Returns an error if a policy with this name already exists.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "legal_hold_policies", + "tags": [ + "Legal hold policies" + ] + }, + "delete": { + "operationId": "delete_legal_hold_policies_id", + "summary": "Remove legal hold policy", + "description": "Delete an existing legal hold policy.\n\nThis is an asynchronous process. The policy will not be\nfully deleted yet when the response returns.", + "parameters": [ + { + "name": "legal_hold_policy_id", + "in": "path", + "description": "The ID of the legal hold policy", + "required": true, + "schema": { + "type": "string" + }, + "example": "324432" + } + ], + "responses": { + "202": { + "description": "A blank response is returned if the policy was\nsuccessfully deleted." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "legal_hold_policies", + "tags": [ + "Legal hold policies" + ] + } + }, + "/legal_hold_policy_assignments": { + "get": { + "operationId": "get_legal_hold_policy_assignments", + "summary": "List legal hold policy assignments", + "description": "Retrieves a list of items a legal hold policy has been assigned to.", + "parameters": [ + { + "name": "policy_id", + "in": "query", + "description": "The ID of the legal hold policy", + "required": true, + "schema": { + "type": "string" + }, + "example": "324432" + }, + { + "name": "assign_to_type", + "in": "query", + "description": "Filters the results by the type of item the\npolicy was applied to.", + "schema": { + "type": "string", + "enum": [ + "file", + "file_version", + "folder", + "user" + ] + }, + "example": "file" + }, + { + "name": "assign_to_id", + "in": "query", + "description": "Filters the results by the ID of item the\npolicy was applied to.", + "schema": { + "type": "string" + }, + "example": "1234323" + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns a list of legal hold policy assignments.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LegalHoldPolicyAssignments" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "legal_hold_policy_assignments", + "tags": [ + "Legal hold policy assignments" + ] + }, + "post": { + "operationId": "post_legal_hold_policy_assignments", + "summary": "Assign legal hold policy", + "description": "Assign a legal hold to a file, file version, folder, or user.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "policy_id": { + "description": "The ID of the policy to assign.", + "type": "string", + "example": "123244" + }, + "assign_to": { + "description": "The item to assign the policy to", + "type": "object", + "properties": { + "type": { + "description": "The type of item to assign the policy to", + "type": "string", + "example": "folder", + "enum": [ + "file", + "file_version", + "folder", + "user" + ] + }, + "id": { + "description": "The ID of item to assign the policy to", + "type": "string", + "example": "6564564" + } + }, + "required": [ + "type", + "id" + ] + } + }, + "required": [ + "policy_id", + "assign_to" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new legal hold policy assignment.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LegalHoldPolicyAssignment" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "legal_hold_policy_assignments", + "tags": [ + "Legal hold policy assignments" + ] + } + }, + "/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}": { + "get": { + "operationId": "get_legal_hold_policy_assignments_id", + "summary": "Get legal hold policy assignment", + "description": "Retrieve a legal hold policy assignment.", + "parameters": [ + { + "name": "legal_hold_policy_assignment_id", + "in": "path", + "description": "The ID of the legal hold policy assignment", + "required": true, + "schema": { + "type": "string" + }, + "example": "753465" + } + ], + "responses": { + "200": { + "description": "Returns a legal hold policy object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LegalHoldPolicyAssignment" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "legal_hold_policy_assignments", + "tags": [ + "Legal hold policy assignments" + ] + }, + "delete": { + "operationId": "delete_legal_hold_policy_assignments_id", + "summary": "Unassign legal hold policy", + "description": "Remove a legal hold from an item.\n\nThis is an asynchronous process. The policy will not be\nfully removed yet when the response returns.", + "parameters": [ + { + "name": "legal_hold_policy_assignment_id", + "in": "path", + "description": "The ID of the legal hold policy assignment", + "required": true, + "schema": { + "type": "string" + }, + "example": "753465" + } + ], + "responses": { + "202": { + "description": "A blank response is returned if the assignment was\nsuccessfully deleted." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "legal_hold_policy_assignments", + "tags": [ + "Legal hold policy assignments" + ] + } + }, + "/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/files_on_hold": { + "get": { + "operationId": "get_legal_hold_policy_assignments_id_files_on_hold", + "summary": "List files with current file versions for legal hold policy assignment", + "description": "Get a list of files with current file versions for a legal hold\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\nThis endpoint does not support returning any content that is on hold due to\na Custodian collaborating on a Hub.\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", + "in": "path", + "description": "The ID of the legal hold policy assignment", + "required": true, + "schema": { + "type": "string" + }, + "example": "753465" + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns the list of current file versions held under legal hold for a\nspecific legal hold policy assignment.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FilesOnHold" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "legal_hold_policy_assignments", + "tags": [ + "Legal hold policy assignments" + ] + } + }, + "/file_version_retentions": { + "get": { + "operationId": "get_file_version_retentions", + "summary": "List file version retentions", + "description": "Retrieves all file version retentions for the given enterprise.\n\n**Note**:\nFile retention API is now **deprecated**. \nTo get information about files and file versions under retention,\nsee [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints.", + "parameters": [ + { + "name": "file_id", + "in": "query", + "description": "Filters results by files with this ID.", + "required": false, + "schema": { + "type": "string" + }, + "example": "43123123" + }, + { + "name": "file_version_id", + "in": "query", + "description": "Filters results by file versions with this ID.", + "required": false, + "schema": { + "type": "string" + }, + "example": "1" + }, + { + "name": "policy_id", + "in": "query", + "description": "Filters results by the retention policy with this ID.", + "required": false, + "schema": { + "type": "string" + }, + "example": "982312" + }, + { + "name": "disposition_action", + "in": "query", + "description": "Filters results by the retention policy with this disposition\naction.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "permanently_delete", + "remove_retention" + ] + }, + "example": "permanently_delete" + }, + { + "name": "disposition_before", + "in": "query", + "description": "Filters results by files that will have their disposition\ncome into effect before this date.", + "required": false, + "schema": { + "type": "string" + }, + "example": "2012-12-12T10:53:43-08:00" + }, + { + "name": "disposition_after", + "in": "query", + "description": "Filters results by files that will have their disposition\ncome into effect after this date.", + "required": false, + "schema": { + "type": "string" + }, + "example": "2012-12-19T10:34:23-08:00" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + } + ], + "responses": { + "200": { + "description": "Returns a list of all file version retentions for the enterprise.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileVersionRetentions" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_version_retentions", + "tags": [ + "File version retentions" + ] + } + }, + "/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/file_versions_on_hold": { + "get": { + "operationId": "get_legal_hold_policy_assignments_id_file_versions_on_hold", + "summary": "List previous file versions for legal hold policy assignment", + "description": "Get a list of previous file versions for a legal hold\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\nThis endpoint does not support returning any content that is on hold due to\na Custodian collaborating on a Hub.\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", + "in": "path", + "description": "The ID of the legal hold policy assignment", + "required": true, + "schema": { + "type": "string" + }, + "example": "753465" + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + } + ], + "responses": { + "200": { + "description": "Returns the list of previous file versions held under legal hold for a\nspecific legal hold policy assignment.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileVersionsOnHold" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "legal_hold_policy_assignments", + "tags": [ + "Legal hold policy assignments" + ] + } + }, + "/file_version_retentions/{file_version_retention_id}": { + "get": { + "operationId": "get_file_version_retentions_id", + "summary": "Get retention on file", + "description": "Returns information about a file version retention.\n\n**Note**:\nFile retention API is now **deprecated**. \nTo get information about files and file versions under retention,\nsee [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints.", + "parameters": [ + { + "name": "file_version_retention_id", + "in": "path", + "description": "The ID of the file version retention", + "required": true, + "schema": { + "type": "string" + }, + "example": "3424234" + } + ], + "responses": { + "200": { + "description": "Returns a file version retention object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileVersionRetention" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_version_retentions", + "tags": [ + "File version retentions" + ] + } + }, + "/file_version_legal_holds/{file_version_legal_hold_id}": { + "get": { + "operationId": "get_file_version_legal_holds_id", + "summary": "Get file version legal hold", + "description": "Retrieves information about the legal hold policies\nassigned to a file version.", + "parameters": [ + { + "name": "file_version_legal_hold_id", + "in": "path", + "description": "The ID of the file version legal hold", + "required": true, + "schema": { + "type": "string" + }, + "example": "2348213" + } + ], + "responses": { + "200": { + "description": "Returns the legal hold policy assignments for the file version.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileVersionLegalHold" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_version_legal_holds", + "tags": [ + "File version legal holds" + ] + } + }, + "/file_version_legal_holds": { + "get": { + "operationId": "get_file_version_legal_holds", + "summary": "List file version legal holds", + "description": "Get a list of file versions on legal hold for a legal hold\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", + "in": "query", + "description": "The ID of the legal hold policy to get the file version legal\nholds for.", + "required": true, + "schema": { + "type": "string" + }, + "example": "133870" + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns the list of file version legal holds for a specific legal\nhold policy.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileVersionLegalHolds" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "file_version_legal_holds", + "tags": [ + "File version legal holds" + ] + } + }, + "/shield_information_barriers/{shield_information_barrier_id}": { + "get": { + "operationId": "get_shield_information_barriers_id", + "summary": "Get shield information barrier with specified ID", + "description": "Get shield information barrier based on provided ID.", + "parameters": [ + { + "name": "shield_information_barrier_id", + "in": "path", + "description": "The ID of the shield information barrier.", + "required": true, + "schema": { + "type": "string" + }, + "example": "1910967" + } + ], + "responses": { + "200": { + "description": "Returns the shield information barrier object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrier" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if\nthe shield information barrier was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barriers", + "tags": [ + "Shield information barriers" + ] + } + }, + "/shield_information_barriers/change_status": { + "post": { + "operationId": "post_shield_information_barriers_change_status", + "summary": "Add changed status of shield information barrier with specified ID", + "description": "Change status of shield information barrier with the specified ID.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "description": "The ID of the shield information barrier.", + "type": "string", + "example": "1910967" + }, + "status": { + "description": "The desired status for the shield information barrier.", + "type": "string", + "example": "pending", + "enum": [ + "pending", + "disabled" + ] + } + }, + "required": [ + "id", + "status" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated shield information barrier object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrier" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if the\nshield information barrier was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error if there exists Conflicts\nwith existing information barriers.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barriers", + "tags": [ + "Shield information barriers" + ] + } + }, + "/shield_information_barriers": { + "get": { + "operationId": "get_shield_information_barriers", + "summary": "List shield information barriers", + "description": "Retrieves a list of shield information barrier objects\nfor the enterprise of JWT.", + "parameters": [ + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a paginated list of\nshield information barrier objects,\nempty list if currently no barrier.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarriers" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if could not find an enterprise using JWT.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barriers", + "tags": [ + "Shield information barriers" + ] + }, + "post": { + "operationId": "post_shield_information_barriers", + "summary": "Create shield information barrier", + "description": "Creates a shield information barrier to\nseparate individuals/groups within the same\nfirm and prevents confidential information passing between them.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "enterprise": { + "description": "The `type` and `id` of enterprise this barrier is under.", + "allOf": [ + { + "$ref": "#/components/schemas/Enterprise--Base" + } + ] + } + }, + "required": [ + "enterprise" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new shield information barrier object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrier" + } + } + } + }, + "404": { + "description": "Returns an error if the enterprise was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barriers", + "tags": [ + "Shield information barriers" + ] + } + }, + "/shield_information_barrier_reports": { + "get": { + "operationId": "get_shield_information_barrier_reports", + "summary": "List shield information barrier reports", + "description": "Lists shield information barrier reports.", + "parameters": [ + { + "name": "shield_information_barrier_id", + "in": "query", + "description": "The ID of the shield information barrier.", + "required": true, + "schema": { + "type": "string" + }, + "example": "1910967" + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a paginated list of shield information barrier report objects.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrierReports" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if the Shield Information Barrier could not be found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_reports", + "tags": [ + "Shield information barrier reports" + ] + }, + "post": { + "operationId": "post_shield_information_barrier_reports", + "summary": "Create shield information barrier report", + "description": "Creates a shield information barrier report for a given barrier.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrierReference" + } + } + } + }, + "responses": { + "201": { + "description": "Returns the shield information barrier report information object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrierReport" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if\nthe shield information barrier report was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns a `conflict` error if a\nshield information barrier report is currently being created.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_reports", + "tags": [ + "Shield information barrier reports" + ] + } + }, + "/shield_information_barrier_reports/{shield_information_barrier_report_id}": { + "get": { + "operationId": "get_shield_information_barrier_reports_id", + "summary": "Get shield information barrier report by ID", + "description": "Retrieves a shield information barrier report by its ID.", + "parameters": [ + { + "name": "shield_information_barrier_report_id", + "in": "path", + "description": "The ID of the shield information barrier Report.", + "required": true, + "schema": { + "type": "string" + }, + "example": "3423" + } + ], + "responses": { + "200": { + "description": "Returns the shield information barrier report object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrierReport" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if the\nshield information barrier Report was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_reports", + "tags": [ + "Shield information barrier reports" + ] + } + }, + "/shield_information_barrier_segments/{shield_information_barrier_segment_id}": { + "get": { + "operationId": "get_shield_information_barrier_segments_id", + "summary": "Get shield information barrier segment with specified ID", + "description": "Retrieves shield information barrier segment based on provided ID..", + "parameters": [ + { + "name": "shield_information_barrier_segment_id", + "in": "path", + "description": "The ID of the shield information barrier segment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "3423" + } + ], + "responses": { + "200": { + "description": "Returns the shield information barrier segment object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegment" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if the\nshield information barrier segment was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_segments", + "tags": [ + "Shield information barrier segments" + ] + }, + "delete": { + "operationId": "delete_shield_information_barrier_segments_id", + "summary": "Delete shield information barrier segment", + "description": "Deletes the shield information barrier segment\nbased on provided ID.", + "parameters": [ + { + "name": "shield_information_barrier_segment_id", + "in": "path", + "description": "The ID of the shield information barrier segment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "3423" + } + ], + "responses": { + "204": { + "description": "Empty body in response" + }, + "404": { + "description": "Returns a `not_found` error if the shield information\nbarrier segment with specified ID was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_segments", + "tags": [ + "Shield information barrier segments" + ] + }, + "put": { + "operationId": "put_shield_information_barrier_segments_id", + "summary": "Update shield information barrier segment with specified ID", + "description": "Updates the shield information barrier segment based on provided ID..", + "parameters": [ + { + "name": "shield_information_barrier_segment_id", + "in": "path", + "description": "The ID of the shield information barrier segment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "3423" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "description": "An object containing update(s) to be made on the Shield\nInformation Barrier Segment. Possible properties include\n'name' and 'description', the value in object is the update.", + "type": "object", + "properties": { + "name": { + "description": "The updated name for the shield information barrier segment.", + "type": "string", + "example": "Investment Banking", + "pattern": "\\S+" + }, + "description": { + "description": "The updated description for\nthe shield information barrier segment.", + "type": "string", + "example": "'Corporate division that engages in advisory_based\nfinancial transactions on behalf of individuals,\ncorporations, and governments.'", + "nullable": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated shield information barrier segment object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegment" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if the shield information\nBarrier Segment was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error if there exists a shield information\nBarrier Segment with the same name.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_segments", + "tags": [ + "Shield information barrier segments" + ] + } + }, + "/shield_information_barrier_segments": { + "get": { + "operationId": "get_shield_information_barrier_segments", + "summary": "List shield information barrier segments", + "description": "Retrieves a list of shield information barrier segment objects\nfor the specified Information Barrier ID.", + "parameters": [ + { + "name": "shield_information_barrier_id", + "in": "query", + "description": "The ID of the shield information barrier.", + "required": true, + "schema": { + "type": "string" + }, + "example": "1910967" + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a paginated list of shield information barrier segment objects.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegments" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if the shield information\nBarrier of given ID was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_segments", + "tags": [ + "Shield information barrier segments" + ] + }, + "post": { + "operationId": "post_shield_information_barrier_segments", + "summary": "Create shield information barrier segment", + "description": "Creates a shield information barrier segment.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "shield_information_barrier": { + "$ref": "#/components/schemas/ShieldInformationBarrier--Base" + }, + "name": { + "description": "Name of the shield information barrier segment", + "type": "string", + "example": "Investment Banking" + }, + "description": { + "description": "Description of the shield information barrier segment", + "type": "string", + "example": "'Corporate division that engages in\n advisory_based financial\ntransactions on behalf of individuals,\ncorporations, and governments.'" + } + }, + "required": [ + "shield_information_barrier", + "name" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new shield information barrier segment object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegment" + } + } + } + }, + "404": { + "description": "Returns an error if the shield information barrier\nwas not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "Returns an error if there exists an shield information \nbarrier segment with same name.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_segments", + "tags": [ + "Shield information barrier segments" + ] + } + }, + "/shield_information_barrier_segment_members/{shield_information_barrier_segment_member_id}": { + "get": { + "operationId": "get_shield_information_barrier_segment_members_id", + "summary": "Get shield information barrier segment member by ID", + "description": "Retrieves a shield information barrier\nsegment member by its ID.", + "parameters": [ + { + "name": "shield_information_barrier_segment_member_id", + "in": "path", + "description": "The ID of the shield information barrier segment Member.", + "required": true, + "schema": { + "type": "string" + }, + "example": "7815" + } + ], + "responses": { + "200": { + "description": "Returns the shield information barrier segment member object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if\nthe shield information barrier segment member was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_segment_members", + "tags": [ + "Shield information barrier segment members" + ] + }, + "delete": { + "operationId": "delete_shield_information_barrier_segment_members_id", + "summary": "Delete shield information barrier segment member by ID", + "description": "Deletes a shield information barrier\nsegment member based on provided ID.", + "parameters": [ + { + "name": "shield_information_barrier_segment_member_id", + "in": "path", + "description": "The ID of the shield information barrier segment Member.", + "required": true, + "schema": { + "type": "string" + }, + "example": "7815" + } + ], + "responses": { + "204": { + "description": "Returns an empty response if the\nsegment member was deleted successfully." + }, + "404": { + "description": "Returns a `not_found` error if the\nshield information barrier segment member was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_segment_members", + "tags": [ + "Shield information barrier segment members" + ] + } + }, + "/shield_information_barrier_segment_members": { + "get": { + "operationId": "get_shield_information_barrier_segment_members", + "summary": "List shield information barrier segment members", + "description": "Lists shield information barrier segment members\nbased on provided segment IDs.", + "parameters": [ + { + "name": "shield_information_barrier_segment_id", + "in": "query", + "description": "The ID of the shield information barrier segment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "3423" + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a paginated list of\nshield information barrier segment member objects.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMembers" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_segment_members", + "tags": [ + "Shield information barrier segment members" + ] + }, + "post": { + "operationId": "post_shield_information_barrier_segment_members", + "summary": "Create shield information barrier segment member", + "description": "Creates a new shield information barrier segment member.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "type": { + "description": "-| A type of the shield barrier segment member.", + "type": "string", + "example": "shield_information_barrier_segment_member", + "enum": [ + "shield_information_barrier_segment_member" + ] + }, + "shield_information_barrier": { + "$ref": "#/components/schemas/ShieldInformationBarrier--Base" + }, + "shield_information_barrier_segment": { + "description": "The `type` and `id` of the\nrequested shield information barrier segment.", + "type": "object", + "properties": { + "id": { + "description": "The ID reference of the\nrequesting shield information barrier segment.", + "type": "string", + "example": "432554" + }, + "type": { + "description": "The type of the shield barrier segment for this member.", + "type": "string", + "example": "shield_information_barrier_segment", + "enum": [ + "shield_information_barrier_segment" + ] + } + } + }, + "user": { + "description": "User to which restriction will be applied.", + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + } + ] + } + }, + "required": [ + "shield_information_barrier_segment", + "user" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new shield information barrier segment member object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember" + } + } + } + }, + "404": { + "description": "Returns an error if the\nshield information barrier or segment was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_segment_members", + "tags": [ + "Shield information barrier segment members" + ] + } + }, + "/shield_information_barrier_segment_restrictions/{shield_information_barrier_segment_restriction_id}": { + "get": { + "operationId": "get_shield_information_barrier_segment_restrictions_id", + "summary": "Get shield information barrier segment restriction by ID", + "description": "Retrieves a shield information barrier segment\nrestriction based on provided ID.", + "parameters": [ + { + "name": "shield_information_barrier_segment_restriction_id", + "in": "path", + "description": "The ID of the shield information barrier segment Restriction.", + "required": true, + "schema": { + "type": "string" + }, + "example": "4563" + } + ], + "responses": { + "200": { + "description": "Returns the shield information barrier segment\nrestriction object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if the\nshield information barrier segment\nrestriction was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_segment_restrictions", + "tags": [ + "Shield information barrier segment restrictions" + ] + }, + "delete": { + "operationId": "delete_shield_information_barrier_segment_restrictions_id", + "summary": "Delete shield information barrier segment restriction by ID", + "description": "Delete shield information barrier segment restriction\nbased on provided ID.", + "parameters": [ + { + "name": "shield_information_barrier_segment_restriction_id", + "in": "path", + "description": "The ID of the shield information barrier segment Restriction.", + "required": true, + "schema": { + "type": "string" + }, + "example": "4563" + } + ], + "responses": { + "204": { + "description": "Empty body in response" + }, + "404": { + "description": "Returns a `not_found` error if the\nshield information barrier segment restriction was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_segment_restrictions", + "tags": [ + "Shield information barrier segment restrictions" + ] + } + }, + "/shield_information_barrier_segment_restrictions": { + "get": { + "operationId": "get_shield_information_barrier_segment_restrictions", + "summary": "List shield information barrier segment restrictions", + "description": "Lists shield information barrier segment restrictions\nbased on provided segment ID.", + "parameters": [ + { + "name": "shield_information_barrier_segment_id", + "in": "query", + "description": "The ID of the shield information barrier segment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "3423" + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a paginated list of\nshield information barrier segment restriction objects.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestrictions" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_segment_restrictions", + "tags": [ + "Shield information barrier segment restrictions" + ] + }, + "post": { + "operationId": "post_shield_information_barrier_segment_restrictions", + "summary": "Create shield information barrier segment restriction", + "description": "Creates a shield information barrier\nsegment restriction object.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "type": { + "description": "The type of the shield barrier segment\nrestriction for this member.", + "type": "string", + "example": "shield_information_barrier_segment_restriction", + "enum": [ + "shield_information_barrier_segment_restriction" + ] + }, + "shield_information_barrier": { + "$ref": "#/components/schemas/ShieldInformationBarrier--Base" + }, + "shield_information_barrier_segment": { + "description": "The `type` and `id` of the requested\nshield information barrier segment.", + "type": "object", + "properties": { + "id": { + "description": "The ID reference of the requesting\nshield information barrier segment.", + "type": "string", + "example": "1910967" + }, + "type": { + "description": "The type of the shield barrier segment for this member.", + "type": "string", + "example": "shield_information_barrier_segment", + "enum": [ + "shield_information_barrier_segment" + ] + } + } + }, + "restricted_segment": { + "description": "The `type` and `id` of the restricted\nshield information barrier segment.", + "type": "object", + "properties": { + "id": { + "description": "The ID reference of the restricted\nshield information barrier segment.", + "type": "string", + "example": "1910967" + }, + "type": { + "description": "The type of the restricted shield\ninformation barrier segment.", + "type": "string", + "example": "shield_information_barrier_segment", + "enum": [ + "shield_information_barrier_segment" + ] + } + } + } + }, + "required": [ + "type", + "shield_information_barrier_segment", + "restricted_segment" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns the newly created Shield\nInformation Barrier Segment Restriction object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if the\nshield information barrier or segment was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_information_barrier_segment_restrictions", + "tags": [ + "Shield information barrier segment restrictions" + ] + } + }, + "/device_pinners/{device_pinner_id}": { + "get": { + "operationId": "get_device_pinners_id", + "summary": "Get device pin", + "description": "Retrieves information about an individual device pin.", + "parameters": [ + { + "name": "device_pinner_id", + "in": "path", + "description": "The ID of the device pin", + "required": true, + "schema": { + "type": "string" + }, + "example": "2324234" + } + ], + "responses": { + "200": { + "description": "Returns information about a single device pin.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DevicePinner" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "device_pinners", + "tags": [ + "Device pinners" + ] + }, + "delete": { + "operationId": "delete_device_pinners_id", + "summary": "Remove device pin", + "description": "Deletes an individual device pin.", + "parameters": [ + { + "name": "device_pinner_id", + "in": "path", + "description": "The ID of the device pin", + "required": true, + "schema": { + "type": "string" + }, + "example": "2324234" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the pin has been deleted." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "device_pinners", + "tags": [ + "Device pinners" + ] + } + }, + "/enterprises/{enterprise_id}/device_pinners": { + "get": { + "operationId": "get_enterprises_id_device_pinners", + "summary": "List enterprise device pins", + "description": "Retrieves all the device pins within an enterprise.\n\nThe user must have admin privileges, and the application\nneeds the \"manage enterprise\" scope to make this call.", + "parameters": [ + { + "name": "enterprise_id", + "in": "path", + "description": "The ID of the enterprise", + "required": true, + "schema": { + "type": "string" + }, + "example": "3442311" + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "direction", + "in": "query", + "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "ASC", + "DESC" + ] + }, + "example": "ASC" + } + ], + "responses": { + "200": { + "description": "Returns a list of device pins for a given enterprise.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DevicePinners" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "device_pinners", + "tags": [ + "Device pinners" + ] + } + }, + "/terms_of_services": { + "get": { + "operationId": "get_terms_of_services", + "summary": "List terms of services", + "description": "Returns the current terms of service text and settings\nfor the enterprise.", + "parameters": [ + { + "name": "tos_type", + "in": "query", + "description": "Limits the results to the terms of service of the given type.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "external", + "managed" + ] + }, + "example": "managed" + } + ], + "responses": { + "200": { + "description": "Returns a collection of terms of service text and settings for the\nenterprise.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TermsOfServices" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "terms_of_services", + "tags": [ + "Terms of service" + ] + }, + "post": { + "operationId": "post_terms_of_services", + "summary": "Create terms of service", + "description": "Creates a terms of service for a given enterprise\nand type of user.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "description": "Whether this terms of service is active.", + "type": "string", + "example": "enabled", + "enum": [ + "enabled", + "disabled" + ] + }, + "tos_type": { + "description": "The type of user to set the terms of\nservice for.", + "type": "string", + "example": "managed", + "enum": [ + "external", + "managed" + ] + }, + "text": { + "description": "The terms of service text to display to users.\n\nThe text can be set to empty if the `status` is set to `disabled`.", + "type": "string", + "example": "By collaborating on this file you are accepting..." + } + }, + "required": [ + "status", + "text" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns a new task object", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TermsOfService" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "terms_of_services", + "tags": [ + "Terms of service" + ] + } + }, + "/terms_of_services/{terms_of_service_id}": { + "get": { + "operationId": "get_terms_of_services_id", + "summary": "Get terms of service", + "description": "Fetches a specific terms of service.", + "parameters": [ + { + "name": "terms_of_service_id", + "in": "path", + "description": "The ID of the terms of service.", + "required": true, + "schema": { + "type": "string" + }, + "example": "324234" + } + ], + "responses": { + "200": { + "description": "Returns a terms of service object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TermsOfService" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "terms_of_services", + "tags": [ + "Terms of service" + ] + }, + "put": { + "operationId": "put_terms_of_services_id", + "summary": "Update terms of service", + "description": "Updates a specific terms of service.", + "parameters": [ + { + "name": "terms_of_service_id", + "in": "path", + "description": "The ID of the terms of service.", + "required": true, + "schema": { + "type": "string" + }, + "example": "324234" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "description": "Whether this terms of service is active.", + "type": "string", + "example": "enabled", + "enum": [ + "enabled", + "disabled" + ] + }, + "text": { + "description": "The terms of service text to display to users.\n\nThe text can be set to empty if the `status` is set to `disabled`.", + "type": "string", + "example": "By collaborating on this file you are accepting..." + } + }, + "required": [ + "status", + "text" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns an updated terms of service object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TermsOfService" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "terms_of_services", + "tags": [ + "Terms of service" + ] + } + }, + "/terms_of_service_user_statuses": { + "get": { + "operationId": "get_terms_of_service_user_statuses", + "summary": "List terms of service user statuses", + "description": "Retrieves an overview of users and their status for a\nterms of service, including Whether they have accepted\nthe terms and when.", + "parameters": [ + { + "name": "tos_id", + "in": "query", + "description": "The ID of the terms of service.", + "required": true, + "schema": { + "type": "string" + }, + "example": "324234" + }, + { + "name": "user_id", + "in": "query", + "description": "Limits results to the given user ID.", + "required": false, + "schema": { + "type": "string" + }, + "example": "123334" + } + ], + "responses": { + "200": { + "description": "Returns a list of terms of service statuses.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TermsOfServiceUserStatuses" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "terms_of_service_user_statuses", + "tags": [ + "Terms of service user statuses" + ] + }, + "post": { + "operationId": "post_terms_of_service_user_statuses", + "summary": "Create terms of service status for new user", + "description": "Sets the status for a terms of service for a user.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "tos": { + "description": "The terms of service to set the status for.", + "type": "object", + "properties": { + "type": { + "description": "The type of object.", + "type": "string", + "example": "terms_of_service", + "enum": [ + "terms_of_service" + ] + }, + "id": { + "description": "The ID of terms of service", + "type": "string", + "example": "1232132" + } + }, + "required": [ + "id", + "type" + ] + }, + "user": { + "description": "The user to set the status for.", + "type": "object", + "properties": { + "type": { + "description": "The type of object.", + "type": "string", + "example": "user", + "enum": [ + "user" + ] + }, + "id": { + "description": "The ID of user", + "type": "string", + "example": "3423423" + } + }, + "required": [ + "id", + "type" + ] + }, + "is_accepted": { + "description": "Whether the user has accepted the terms.", + "type": "boolean", + "example": true + } + }, + "required": [ + "tos", + "user", + "is_accepted" + ] + } + } + } + }, + "responses": { + "201": { + "description": "Returns a terms of service status object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TermsOfServiceUserStatus" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "terms_of_service_user_statuses", + "tags": [ + "Terms of service user statuses" + ] + } + }, + "/terms_of_service_user_statuses/{terms_of_service_user_status_id}": { + "put": { + "operationId": "put_terms_of_service_user_statuses_id", + "summary": "Update terms of service status for existing user", + "description": "Updates the status for a terms of service for a user.", + "parameters": [ + { + "name": "terms_of_service_user_status_id", + "in": "path", + "description": "The ID of the terms of service status.", + "required": true, + "schema": { + "type": "string" + }, + "example": "324234" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "is_accepted": { + "description": "Whether the user has accepted the terms.", + "type": "boolean", + "example": true + } + }, + "required": [ + "is_accepted" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated terms of service status object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TermsOfServiceUserStatus" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "terms_of_service_user_statuses", + "tags": [ + "Terms of service user statuses" + ] + } + }, + "/collaboration_whitelist_entries": { + "get": { + "operationId": "get_collaboration_whitelist_entries", + "summary": "List allowed collaboration domains", + "description": "Returns the list domains that have been deemed safe to create collaborations\nfor within the current enterprise.", + "parameters": [ + { + "name": "marker", + "in": "query", + "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`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a collection of domains that are allowed for collaboration.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CollaborationAllowlistEntries" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "collaboration_allowlist_entries", + "tags": [ + "Domain restrictions for collaborations" + ] + }, + "post": { + "operationId": "post_collaboration_whitelist_entries", + "summary": "Add domain to list of allowed collaboration domains", + "description": "Creates a new entry in the list of allowed domains to allow\ncollaboration for.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "domain": { + "description": "The domain to add to the list of allowed domains.", + "type": "string", + "example": "example.com" + }, + "direction": { + "description": "The direction in which to allow collaborations.", + "type": "string", + "example": "inbound", + "enum": [ + "inbound", + "outbound", + "both" + ] + } + }, + "required": [ + "domain", + "direction" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns a new entry on the list of allowed domains.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CollaborationAllowlistEntry" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "collaboration_allowlist_entries", + "tags": [ + "Domain restrictions for collaborations" + ] + } + }, + "/collaboration_whitelist_entries/{collaboration_whitelist_entry_id}": { + "get": { + "operationId": "get_collaboration_whitelist_entries_id", + "summary": "Get allowed collaboration domain", + "description": "Returns a domain that has been deemed safe to create collaborations\nfor within the current enterprise.", + "parameters": [ + { + "name": "collaboration_whitelist_entry_id", + "in": "path", + "description": "The ID of the entry in the list.", + "required": true, + "schema": { + "type": "string" + }, + "example": "213123" + } + ], + "responses": { + "200": { + "description": "Returns an entry on the list of allowed domains.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CollaborationAllowlistEntry" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "collaboration_allowlist_entries", + "tags": [ + "Domain restrictions for collaborations" + ] + }, + "delete": { + "operationId": "delete_collaboration_whitelist_entries_id", + "summary": "Remove domain from list of allowed collaboration domains", + "description": "Removes a domain from the list of domains that have been deemed safe to create\ncollaborations for within the current enterprise.", + "parameters": [ + { + "name": "collaboration_whitelist_entry_id", + "in": "path", + "description": "The ID of the entry in the list.", + "required": true, + "schema": { + "type": "string" + }, + "example": "213123" + } + ], + "responses": { + "204": { + "description": "A blank response is returned if the entry was\nsuccessfully deleted." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "collaboration_allowlist_entries", + "tags": [ + "Domain restrictions for collaborations" + ] + } + }, + "/collaboration_whitelist_exempt_targets": { + "get": { + "operationId": "get_collaboration_whitelist_exempt_targets", + "summary": "List users exempt from collaboration domain restrictions", + "description": "Returns a list of users who have been exempt from the collaboration\ndomain restrictions.", + "parameters": [ + { + "name": "marker", + "in": "query", + "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`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a collection of user exemptions.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CollaborationAllowlistExemptTargets" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "collaboration_allowlist_exempt_targets", + "tags": [ + "Domain restrictions (User exemptions)" + ] + }, + "post": { + "operationId": "post_collaboration_whitelist_exempt_targets", + "summary": "Create user exemption from collaboration domain restrictions", + "description": "Exempts a user from the restrictions set out by the allowed list of domains\nfor collaborations.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "user": { + "description": "The user to exempt.", + "type": "object", + "properties": { + "id": { + "description": "The ID of the user to exempt.", + "type": "string", + "example": "23522323" + } + }, + "required": [ + "id" + ] + } + }, + "required": [ + "user" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns a new exemption entry.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CollaborationAllowlistExemptTarget" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "collaboration_allowlist_exempt_targets", + "tags": [ + "Domain restrictions (User exemptions)" + ] + } + }, + "/collaboration_whitelist_exempt_targets/{collaboration_whitelist_exempt_target_id}": { + "get": { + "operationId": "get_collaboration_whitelist_exempt_targets_id", + "summary": "Get user exempt from collaboration domain restrictions", + "description": "Returns a users who has been exempt from the collaboration\ndomain restrictions.", + "parameters": [ + { + "name": "collaboration_whitelist_exempt_target_id", + "in": "path", + "description": "The ID of the exemption to the list.", + "required": true, + "schema": { + "type": "string" + }, + "example": "984923" + } + ], + "responses": { + "200": { + "description": "Returns the user's exempted from the list of collaboration domains.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CollaborationAllowlistExemptTarget" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "collaboration_allowlist_exempt_targets", + "tags": [ + "Domain restrictions (User exemptions)" + ] + }, + "delete": { + "operationId": "delete_collaboration_whitelist_exempt_targets_id", + "summary": "Remove user from list of users exempt from domain restrictions", + "description": "Removes a user's exemption from the restrictions set out by the allowed list\nof domains for collaborations.", + "parameters": [ + { + "name": "collaboration_whitelist_exempt_target_id", + "in": "path", + "description": "The ID of the exemption to the list.", + "required": true, + "schema": { + "type": "string" + }, + "example": "984923" + } + ], + "responses": { + "204": { + "description": "A blank response is returned if the exemption was\nsuccessfully deleted." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "collaboration_allowlist_exempt_targets", + "tags": [ + "Domain restrictions (User exemptions)" + ] + } + }, + "/storage_policies": { + "get": { + "operationId": "get_storage_policies", + "summary": "List storage policies", + "description": "Fetches all the storage policies in the enterprise.", + "parameters": [ + { + "name": "fields", + "in": "query", + "description": "A comma-separated list of attributes to include in the\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.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "example": [ + "id", + "type", + "name" + ], + "explode": false + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a collection of storage policies.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StoragePolicies" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "storage_policies", + "tags": [ + "Standard and Zones Storage Policies" + ] + } + }, + "/storage_policies/{storage_policy_id}": { + "get": { + "operationId": "get_storage_policies_id", + "summary": "Get storage policy", + "description": "Fetches a specific storage policy.", + "parameters": [ + { + "name": "storage_policy_id", + "in": "path", + "description": "The ID of the storage policy.", + "required": true, + "schema": { + "type": "string" + }, + "example": "34342" + } + ], + "responses": { + "200": { + "description": "Returns a storage policy object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StoragePolicy" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "storage_policies", + "tags": [ + "Standard and Zones Storage Policies" + ] + } + }, + "/storage_policy_assignments": { + "get": { + "operationId": "get_storage_policy_assignments", + "summary": "List storage policy assignments", + "description": "Fetches all the storage policy assignment for an enterprise or user.", + "parameters": [ + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "resolved_for_type", + "in": "query", + "description": "The target type to return assignments for", + "required": true, + "schema": { + "type": "string", + "enum": [ + "user", + "enterprise" + ] + }, + "example": "user" + }, + { + "name": "resolved_for_id", + "in": "query", + "description": "The ID of the user or enterprise to return assignments for", + "required": true, + "schema": { + "type": "string" + }, + "example": "984322" + } + ], + "responses": { + "200": { + "description": "Returns a collection of storage policies for\nthe enterprise or user.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StoragePolicyAssignments" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "storage_policy_assignments", + "tags": [ + "Standard and Zones Storage Policy Assignments" + ] + }, + "post": { + "operationId": "post_storage_policy_assignments", + "summary": "Assign storage policy", + "description": "Creates a storage policy assignment for an enterprise or user.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "storage_policy": { + "description": "The storage policy to assign to the user or\nenterprise", + "type": "object", + "properties": { + "type": { + "description": "The type to assign.", + "type": "string", + "example": "storage_policy", + "enum": [ + "storage_policy" + ] + }, + "id": { + "description": "The ID of the storage policy to assign.", + "type": "string", + "example": "1434325" + } + }, + "required": [ + "type", + "id" + ] + }, + "assigned_to": { + "description": "The user or enterprise to assign the storage\npolicy to.", + "type": "object", + "properties": { + "type": { + "description": "The type to assign the policy to.", + "type": "string", + "example": "user", + "enum": [ + "user", + "enterprise" + ] + }, + "id": { + "description": "The ID of the user or enterprise", + "type": "string", + "example": "9987987" + } + }, + "required": [ + "type", + "id" + ] + } + }, + "required": [ + "storage_policy", + "assigned_to" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns the new storage policy assignment created.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StoragePolicyAssignment" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "storage_policy_assignments", + "tags": [ + "Standard and Zones Storage Policy Assignments" + ] + } + }, + "/storage_policy_assignments/{storage_policy_assignment_id}": { + "get": { + "operationId": "get_storage_policy_assignments_id", + "summary": "Get storage policy assignment", + "description": "Fetches a specific storage policy assignment.", + "parameters": [ + { + "name": "storage_policy_assignment_id", + "in": "path", + "description": "The ID of the storage policy assignment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "932483" + } + ], + "responses": { + "200": { + "description": "Returns a storage policy assignment object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StoragePolicyAssignment" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "storage_policy_assignments", + "tags": [ + "Standard and Zones Storage Policy Assignments" + ] + }, + "put": { + "operationId": "put_storage_policy_assignments_id", + "summary": "Update storage policy assignment", + "description": "Updates a specific storage policy assignment.", + "parameters": [ + { + "name": "storage_policy_assignment_id", + "in": "path", + "description": "The ID of the storage policy assignment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "932483" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "storage_policy": { + "description": "The storage policy to assign to the user or\nenterprise", + "type": "object", + "properties": { + "type": { + "description": "The type to assign.", + "type": "string", + "example": "storage_policy", + "enum": [ + "storage_policy" + ] + }, + "id": { + "description": "The ID of the storage policy to assign.", + "type": "string", + "example": "1434325" + } + }, + "required": [ + "type", + "id" + ] + } + }, + "required": [ + "storage_policy" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Returns an updated storage policy assignment object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StoragePolicyAssignment" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "storage_policy_assignments", + "tags": [ + "Standard and Zones Storage Policy Assignments" + ] + }, + "delete": { + "operationId": "delete_storage_policy_assignments_id", + "summary": "Unassign storage policy", + "description": "Delete a storage policy assignment.\n\nDeleting a storage policy assignment on a user\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", + "in": "path", + "description": "The ID of the storage policy assignment.", + "required": true, + "schema": { + "type": "string" + }, + "example": "932483" + } + ], + "responses": { + "204": { + "description": "Returns an empty response when the storage policy\nassignment is successfully deleted." + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "storage_policy_assignments", + "tags": [ + "Standard and Zones Storage Policy Assignments" + ] + } + }, + "/zip_downloads": { + "post": { + "operationId": "post_zip_downloads", + "summary": "Create zip download", + "description": "Creates a request to download multiple files and folders as a single `zip`\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.\n\n**Note**: Downloading a large file can be\naffected by various\nfactors such as distance, network latency,\nbandwidth, and congestion, as well as packet loss\nratio and current server load.\nFor these reasons we recommend that a maximum ZIP archive\ntotal size does not exceed 25GB.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ZipDownloadRequest" + } + } + } + }, + "responses": { + "202": { + "description": "If the `zip` archive is ready to be downloaded, the API will return a\nresponse that will include a `download_url`, a `status_url`, as well as\nany conflicts that might have occurred when creating the request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ZipDownload" + }, + "examples": { + "default": { + "value": { + "download_url": "https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content", + "status_url": "https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status", + "expires_at": "2020-07-22T11:26:08Z", + "name_conflicts": [ + [ + { + "id": "12345", + "type": "file", + "original_name": "Report.pdf", + "download_name": "3aa6a7.pdf" + }, + { + "id": "34325", + "type": "file", + "original_name": "Report.pdf", + "download_name": "5d53f2.pdf" + } + ] + ] + } + } + } + } + } + }, + "400": { + "description": "Returns an error if some of the parameters are missing or\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.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned when an authorization header is provided but the user does not\nhave access to the items.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "zip_downloads", + "tags": [ + "Zip Downloads" + ], + "x-box-reference-category": "zip_downloads" + } + }, + "/zip_downloads/{zip_download_id}/content": { + "get": { + "operationId": "get_zip_downloads_id_content", + "summary": "Download zip archive", + "description": "Returns the contents of a `zip` archive in binary format. This URL does not\nrequire any form of authentication and could be used in a user's browser to\ndownload the archive to a user's device.\n\nBy default, this URL is only valid for a few seconds from the creation of\nthe request for this archive. Once a download has started it can not be\nstopped and resumed, instead a new request for a zip archive would need to\nbe created.\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 `download_url` field in the response to\nthis endpoint.", + "parameters": [ + { + "name": "zip_download_id", + "in": "path", + "description": "The unique identifier that represent this `zip` archive.", + "required": true, + "schema": { + "type": "string" + }, + "example": "Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd" + } + ], + "responses": { + "200": { + "description": "Returns the content of the items requested for this download, formatted as\na stream of files and folders in a `zip` archive.", + "headers": { + "Content-Disposition": { + "description": "The name of the archive to be downloaded", + "schema": { + "type": "string", + "example": "attachment;filename=\"Avatars.zip\";filename*=UTF-8''Avatars.zip" + } + } + }, + "content": { + "application/octet-stream": { + "schema": { + "description": "The binary content of the archive, which will include the items\nrequested for this download.", + "type": "string", + "format": "binary" + } + } + } + }, + "404": { + "description": "Returns an error if the ID of this download request is not valid. This\nerror can also be returned if this URL has been called before. To\nre-download this archive, please create a new request for a zip download.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "429": { + "description": "Returns an error if the number of concurrent zip downloads has been\nreached for either the user or the enterprise.\n\n* `user_too_many_concurrent_downloads` - the maximum of 5 parallel\ndownloads of zip archives per user has been met.\n* `enterprise_too_many_concurrent_downloads` - the maximum of 10 parallel\ndownloads of zip archives per enterprise has been met.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "zip_downloads", + "security": [], + "servers": [ + { + "url": "https://dl.boxcloud.com/2.0", + "description": "An opaque server URL for downloading zip downloads. The format\nof this URL might change over time." + } + ], + "tags": [ + "Zip Downloads" + ], + "x-box-reference-category": "zip_downloads" + } + }, + "/zip_downloads/{zip_download_id}/status": { + "get": { + "operationId": "get_zip_downloads_id_status", + "summary": "Get zip download status", + "description": "Returns the download status of a `zip` archive, allowing an application to\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", + "in": "path", + "description": "The unique identifier that represent this `zip` archive.", + "required": true, + "schema": { + "type": "string" + }, + "example": "Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd" + } + ], + "responses": { + "200": { + "description": "Returns the status of the `zip` archive that is being downloaded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ZipDownloadStatus" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned when an authorization header is provided but the user does not\nhave access to the items.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns an error if the ID of this download request is not valid, or if\nthe status of a download is requested before the download has been\nstarted.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "zip_downloads", + "tags": [ + "Zip Downloads" + ], + "x-box-reference-category": "zip_downloads" + } + }, + "/sign_requests/{sign_request_id}/cancel": { + "post": { + "operationId": "post_sign_requests_id_cancel", + "summary": "Cancel Box Sign request", + "description": "Cancels a sign request.", + "parameters": [ + { + "name": "sign_request_id", + "in": "path", + "description": "The ID of the signature request", + "required": true, + "schema": { + "type": "string" + }, + "example": "33243242" + } + ], + "responses": { + "200": { + "description": "Returns a Sign Request object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SignRequest" + } + } + } + }, + "404": { + "description": "Returns an error when the sign request cannot be found or the user does\nnot have access to the sign request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "sign_requests", + "tags": [ + "Sign requests" + ] + } + }, + "/sign_requests/{sign_request_id}/resend": { + "post": { + "operationId": "post_sign_requests_id_resend", + "summary": "Resend Box Sign request", + "description": "Resends a signature request email to all outstanding signers.", + "parameters": [ + { + "name": "sign_request_id", + "in": "path", + "description": "The ID of the signature request", + "required": true, + "schema": { + "type": "string" + }, + "example": "33243242" + } + ], + "responses": { + "202": { + "description": "Returns an empty response when the API call was successful.\nThe email notifications will be sent asynchronously." + }, + "404": { + "description": "Returns an error when the signature request cannot be found or the user does\nnot have access to the signature request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "sign_requests", + "tags": [ + "Sign requests" + ] + } + }, + "/sign_requests/{sign_request_id}": { + "get": { + "operationId": "get_sign_requests_id", + "summary": "Get Box Sign request by ID", + "description": "Gets a sign request by ID.", + "parameters": [ + { + "name": "sign_request_id", + "in": "path", + "description": "The ID of the signature request", + "required": true, + "schema": { + "type": "string" + }, + "example": "33243242" + } + ], + "responses": { + "200": { + "description": "Returns a signature request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SignRequest" + } + } + } + }, + "404": { + "description": "Returns an error when the signature request cannot be found, the user does\nnot have access to the signature request, or `sign_files` and/or\n`parent_folder` is deleted.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "sign_requests", + "tags": [ + "Sign requests" + ] + } + }, + "/sign_requests": { + "get": { + "operationId": "get_sign_requests", + "summary": "List Box Sign requests", + "description": "Gets signature requests created by a user. If the `sign_files` and/or\n`parent_folder` are deleted, the signature request will not return in the list.", + "parameters": [ + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a collection of sign requests", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SignRequests" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "sign_requests", + "tags": [ + "Sign requests" + ] + }, + "post": { + "operationId": "post_sign_requests", + "summary": "Create Box Sign request", + "description": "Creates a signature request. This involves preparing a document for signing and\nsending the signature request to signers.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SignRequestCreateRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Returns a Box Sign request object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SignRequest" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "sign_requests", + "tags": [ + "Sign requests" + ] + } + }, + "/workflows": { + "get": { + "operationId": "get_workflows", + "summary": "List 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", + "in": "query", + "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`.", + "required": true, + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "trigger_type", + "in": "query", + "description": "Type of trigger to search for.", + "required": false, + "schema": { + "type": "string", + "nullable": false + }, + "example": "WORKFLOW_MANUAL_START" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + } + ], + "responses": { + "200": { + "description": "Returns the workflow.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Workflows" + } + } + } + }, + "400": { + "description": "Returned if the trigger type is not `WORKFLOW_MANUAL_START`.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "workflows", + "tags": [ + "Workflows" + ] + } + }, + "/workflows/{workflow_id}/start": { + "post": { + "operationId": "post_workflows_id_start", + "summary": "Starts workflow based on request body", + "description": "Initiates a flow with a trigger type of `WORKFLOW_MANUAL_START`.\n\nYou application must be authorized to use the `Manage Box Relay` application\nscope within the developer console.", + "parameters": [ + { + "name": "workflow_id", + "in": "path", + "description": "The ID of the workflow.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "type": { + "description": "The type of the parameters object", + "type": "string", + "example": "workflow_parameters", + "enum": [ + "workflow_parameters" + ] + }, + "flow": { + "description": "The flow that will be triggered", + "type": "object", + "properties": { + "type": { + "description": "The type of the flow object", + "type": "string", + "example": "flow" + }, + "id": { + "description": "The id of the flow", + "type": "string", + "example": "123456789" + } + } + }, + "files": { + "description": "The array of files for which the workflow should start. All files\nmust be in the workflow's configured folder.", + "type": "array", + "items": { + "type": "object", + "description": "A file the workflow should start for", + "properties": { + "type": { + "description": "The type of the file object", + "type": "string", + "example": "file", + "enum": [ + "file" + ] + }, + "id": { + "description": "The id of the file", + "type": "string", + "example": "12345678" + } + } + } + }, + "folder": { + "description": "The folder object for which the workflow is configured.", + "type": "object", + "properties": { + "type": { + "description": "The type of the folder object", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ] + }, + "id": { + "description": "The id of the folder", + "type": "string", + "example": "87654321" + } + } + }, + "outcomes": { + "description": "A configurable outcome the workflow should complete.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Outcome" + } + } + }, + "required": [ + "flow", + "files", + "folder" + ] + } + } + } + }, + "responses": { + "204": { + "description": "Starts the workflow." + }, + "400": { + "description": "Returns an error if some of the parameters are missing or\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", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returns an error if there are insufficient permissions.\n\n* `insufficient_access` when the user does not have access rights to file\n or folder\n* `missing_relay_full_access` when the user does not have access to Relay\n Full", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/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", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "workflows", + "tags": [ + "Workflows" + ] + } + }, + "/sign_templates": { + "get": { + "operationId": "get_sign_templates", + "summary": "List Box Sign templates", + "description": "Gets Box Sign templates created by a user.", + "parameters": [ + { + "name": "marker", + "in": "query", + "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + } + ], + "responses": { + "200": { + "description": "Returns a collection of templates.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SignTemplates" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "sign_templates", + "tags": [ + "Sign templates" + ] + } + }, + "/sign_templates/{template_id}": { + "get": { + "operationId": "get_sign_templates_id", + "summary": "Get Box Sign template by ID", + "description": "Fetches details of a specific Box Sign template.", + "parameters": [ + { + "name": "template_id", + "in": "path", + "description": "The ID of a Box Sign template.", + "required": true, + "schema": { + "type": "string" + }, + "example": "123075213-7d117509-8f05-42e4-a5ef-5190a319d41d" + } + ], + "responses": { + "200": { + "description": "Returns details of a template.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SignTemplate" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned if the template is not found or the user does not\nhave access to the associated template.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "sign_templates", + "tags": [ + "Sign templates" + ] + } + }, + "/integration_mappings/slack": { + "get": { + "operationId": "get_integration_mappings_slack", + "summary": "List Slack integration mappings", + "description": "Lists [Slack integration mappings](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) in a users' enterprise.\n\nYou need Admin or Co-Admin role to\nuse this endpoint.", + "parameters": [ + { + "name": "marker", + "in": "query", + "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`.", + "required": false, + "schema": { + "type": "string" + }, + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" + }, + { + "name": "limit", + "in": "query", + "description": "The maximum number of items to return per page.", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "maximum": 1000 + }, + "example": 1000 + }, + { + "name": "partner_item_type", + "in": "query", + "description": "Mapped item type, for which the mapping should be returned", + "schema": { + "type": "string", + "enum": [ + "channel" + ], + "nullable": false + }, + "example": "channel" + }, + { + "name": "partner_item_id", + "in": "query", + "description": "ID of the mapped item, for which the mapping should be returned", + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "box_item_id", + "in": "query", + "description": "Box item ID, for which the mappings should be returned", + "schema": { + "type": "string", + "nullable": false + }, + "example": "12345" + }, + { + "name": "box_item_type", + "in": "query", + "description": "Box item type, for which the mappings should be returned", + "schema": { + "type": "string", + "enum": [ + "folder" + ], + "nullable": false + }, + "example": "folder" + }, + { + "name": "is_manually_created", + "in": "query", + "description": "Whether the mapping has been manually created", + "schema": { + "type": "boolean", + "nullable": false + }, + "example": true + } + ], + "responses": { + "200": { + "description": "Returns a collection of integration mappings", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationMappings" + } + } + } + }, + "400": { + "description": "The server cannot or will not process the\nrequest due to an apparent client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if the integration mapping could not be found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "integration_mappings", + "tags": [ + "Integration mappings" + ] + }, + "post": { + "operationId": "post_integration_mappings_slack", + "summary": "Create Slack integration mapping", + "description": "Creates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack)\nby mapping a Slack channel to a Box item.\n\nYou need Admin or Co-Admin role to\nuse this endpoint.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationMappingSlackCreateRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Returns the created integration mapping.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationMapping" + } + } + } + }, + "400": { + "description": "Returns a `bad_request` if an incorrect `options`\nwas supplied or the Box folder cannot be\nmapped to this `partner_item_id`.\nError codes:\n* `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account\ndoesn't have co-owner collaboration or is\nnot an owner of the `box_item_id`,\n* `CHANNEL_ALREADY_MAPPED` - channel is already\n mapped to another `box_item_id`,\n* `CHANNEL_NOT_FOUND` - channel was not found,\n* `CHANNEL_NOT_SUITABLE_FOR_CFS` - connect channel, not\nsuitable for Box as Content layer for Slack,\n* `BOX_ENTERPRISE_MISMATCH` - Box folder must be\nowned by the enterprise, which is configured\nto use Box as Content layer for Slack,\n* `CFS_DISABLED` - Box as Content layer\nfor Slack must be enabled for a provided\nSlack workspace or organization\n* `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must\nbe internally owned to the admin's enterprise,\n* `JWT_APP_NOT_AUTHORIZED` - JWT authorization error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns a `not_found` error if the integration mapping could not be found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "integration_mappings", + "tags": [ + "Integration mappings" + ] + } + }, + "/integration_mappings/slack/{integration_mapping_id}": { + "put": { + "operationId": "put_integration_mappings_slack_id", + "summary": "Update Slack integration mapping", + "description": "Updates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack).\nSupports updating the Box folder ID and options.\n\nYou need Admin or Co-Admin role to\nuse this endpoint.", + "parameters": [ + { + "name": "integration_mapping_id", + "in": "path", + "description": "An ID of an integration mapping", + "required": true, + "schema": { + "type": "string" + }, + "example": "11235432" + } + ], + "requestBody": { + "description": "At least one of `box_item` and `options` must be provided.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "box_item": { + "allOf": [ + { + "$ref": "#/components/schemas/IntegrationMappingBoxItemSlack" + } + ], + "nullable": false + }, + "options": { + "allOf": [ + { + "$ref": "#/components/schemas/IntegrationMappingSlackOptions" + } + ], + "nullable": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Returns the updated integration mapping object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IntegrationMapping" + } + } + } + }, + "400": { + "description": "Returns a `bad_request` if an incorrect `options` was\nsupplied or the Box folder cannot be mapped to this `partner_item`.\nError codes:\n* `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account\n doesn't have co-owner collaboration or is\n not an owner of the `box_item_id`,\n* `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be\n internally owned to the admin's enterprise,\n* `JWT_APP_NOT_AUTHORIZED` - JWT authorization error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returns `not_found` if integration mapping object was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "integration_mappings", + "tags": [ + "Integration mappings" + ] + }, + "delete": { + "operationId": "delete_integration_mappings_slack_id", + "summary": "Delete Slack integration mapping", + "description": "Deletes a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack).\n\n\nYou need Admin or Co-Admin role to\nuse this endpoint.", + "parameters": [ + { + "name": "integration_mapping_id", + "in": "path", + "description": "An ID of an integration mapping", + "required": true, + "schema": { + "type": "string" + }, + "example": "11235432" + } + ], + "responses": { + "204": { + "description": "Empty body in response" + }, + "404": { + "description": "Returns a `not_found` error if the integration mapping could not be found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "integration_mappings", + "tags": [ + "Integration mappings" + ] + } + }, + "/ai/ask": { + "post": { + "operationId": "post_ai_ask", + "summary": "Ask question", + "description": "Sends an AI request to supported LLMs and returns an answer specifically focused on the user's question given the provided context.", + "x-stability-level": "stable", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AiAsk" + } + } + } + }, + "responses": { + "200": { + "description": "A successful response including the answer from the LLM.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AiResponse--Full" + } + } + } + }, + "500": { + "description": "An unexpected server error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "ai", + "tags": [ + "AI" + ], + "x-box-enable-explorer": false + } + }, + "/ai/text_gen": { + "post": { + "operationId": "post_ai_text_gen", + "summary": "Generate text", + "description": "Sends an AI request to supported Large Language Models (LLMs) and returns generated text based on the provided prompt.", + "x-stability-level": "stable", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AiTextGen" + } + } + } + }, + "responses": { + "200": { + "description": "A successful response including the answer from the LLM.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AiResponse" + } + } + } + }, + "500": { + "description": "An unexpected server error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "ai", + "tags": [ + "AI" + ], + "x-box-enable-explorer": false + } + }, + "/ai_agent_default": { + "get": { + "operationId": "get_ai_agent_default", + "summary": "Get AI agent default configuration", + "description": "Get the AI agent default config", + "x-stability-level": "stable", + "parameters": [ + { + "name": "mode", + "in": "query", + "description": "The mode to filter the agent config to return.", + "required": true, + "schema": { + "type": "string", + "enum": [ + "ask", + "text_gen", + "extract", + "extract_structured" + ] + }, + "example": "ask" + }, + { + "name": "language", + "in": "query", + "description": "The ISO language code to return the agent config for.\nIf the language is not supported the default agent config is returned.", + "required": false, + "schema": { + "type": "string" + }, + "example": "ja" + }, + { + "name": "model", + "in": "query", + "description": "The model to return the default agent config for.", + "required": false, + "schema": { + "type": "string" + }, + "example": "openai__gpt_3_5_turbo" + } + ], + "responses": { + "200": { + "description": "A successful response including the default agent configuration.\nThis response can be one of the following four objects:\n* AI agent for questions\n* AI agent for text generation\n* AI agent for freeform metadata extraction\n* AI agent for structured metadata extraction.\nThe response depends on the agent configuration requested in this endpoint.", + "content": { + "application/json": { + "schema": { + "oneOf": [ + { + "$ref": "#/components/schemas/AiAgentAsk" + }, + { + "$ref": "#/components/schemas/AiAgentTextGen" + }, + { + "$ref": "#/components/schemas/AiAgentExtract" + }, + { + "$ref": "#/components/schemas/AiAgentExtractStructured" + } + ] + } + } + } + }, + "500": { + "description": "An unexpected server error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "ai", + "tags": [ + "AI" + ], + "x-box-enable-explorer": false + } + }, + "/ai/extract": { + "post": { + "operationId": "post_ai_extract", + "summary": "Extract metadata (freeform)", + "description": "Sends an AI request to supported Large Language Models (LLMs) and extracts metadata in form of key-value pairs.\nFreeform metadata extraction does not require any metadata template setup before sending the request.", + "x-stability-level": "beta", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AiExtract" + } + } + } + }, + "responses": { + "200": { + "description": "A response including the answer from the LLM.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AiResponse" + } + } + } + }, + "500": { + "description": "An unexpected server error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "ai", + "tags": [ + "AI" + ], + "x-box-enable-explorer": false + } + }, + "/ai/extract_structured": { + "post": { + "operationId": "post_ai_extract_structured", + "summary": "Extract metadata (structured)", + "description": "Sends an AI request to supported Large Language Models (LLMs) and returns extracted metadata as a set of key-value pairs.\nFor this request, you need to use an already defined metadata template or a define a schema yourself.\nTo learn more about creating templates, see [Creating metadata templates in the Admin Console](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates)\nor use the [metadata template API](g://metadata/templates/create).", + "x-stability-level": "beta", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AiExtractStructured" + } + } + } + }, + "responses": { + "200": { + "description": "A successful response including the answer from the LLM.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AiExtractResponse" + } + } + } + }, + "500": { + "description": "An unexpected server error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "ai", + "tags": [ + "AI" + ], + "x-box-enable-explorer": false + } + } + }, + "components": { + "schemas": { + "AccessToken": { + "description": "A token that can be used to make authenticated API calls.", + "type": "object", + "properties": { + "access_token": { + "description": "The requested access token.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + }, + "expires_in": { + "description": "The time in seconds by which this token will expire.", + "type": "integer", + "format": "int64", + "example": 3600 + }, + "token_type": { + "description": "The type of access token returned.", + "type": "string", + "example": "bearer", + "enum": [ + "bearer" + ] + }, + "restricted_to": { + "description": "The permissions that this access token permits,\nproviding a list of resources (files, folders, etc)\nand the scopes permitted for each of those resources.", + "type": "array", + "items": { + "$ref": "#/components/schemas/FileOrFolderScope" + } + }, + "refresh_token": { + "description": "The refresh token for this access token, which can be used\nto request a new access token when the current one expires.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + }, + "issued_token_type": { + "description": "The type of downscoped access token returned. This is only\nreturned if an access token has been downscoped.", + "type": "string", + "format": "urn", + "example": "urn:ietf:params:oauth:token-type:access_token", + "enum": [ + "urn:ietf:params:oauth:token-type:access_token" + ] + } + }, + "title": "Access token", + "x-box-resource-id": "access_token", + "x-box-tag": "authorization" + }, + "AiAgentAsk": { + "description": "The AI agent used to handle queries.", + "type": "object", + "properties": { + "type": { + "description": "The type of AI agent used to handle queries.", + "type": "string", + "example": "ai_agent_ask", + "enum": [ + "ai_agent_ask" + ], + "nullable": false + }, + "long_text": { + "$ref": "#/components/schemas/AiAgentLongTextTool" + }, + "basic_text": { + "$ref": "#/components/schemas/AiAgentBasicTextTool" + }, + "long_text_multi": { + "$ref": "#/components/schemas/AiAgentLongTextTool" + }, + "basic_text_multi": { + "$ref": "#/components/schemas/AiAgentBasicTextTool" + } + }, + "required": [ + "type" + ], + "title": "AI agent for question requests", + "x-box-resource-id": "ai_agent_ask", + "x-box-tag": "ai" + }, + "AiAgentBasicGenTool": { + "description": "AI agent basic tool used to generate text. ", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/AiAgentLongTextToolTextGen" + }, + { + "properties": { + "content_template": { + "description": "How the content should be included in a request to the LLM.\nInput for `{content}` is optional, depending on the use.", + "type": "string", + "example": "---{content}---" + } + } + } + ], + "title": "AI agent basic text generation tool", + "x-box-tag": "ai" + }, + "AiAgentBasicTextTool": { + "description": "AI agent tool used to handle basic text.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/AiAgentBasicTextToolBase" + }, + { + "properties": { + "system_message": { + "description": "System messages try to help the LLM \"understand\" its role and what it is supposed to do.", + "type": "string", + "example": "You are a helpful travel assistant specialized in budget travel" + }, + "prompt_template": { + "description": "The prompt template contains contextual information of the request and the user prompt.\nWhen passing `prompt_template` parameters, you **must include** inputs for `{user_question}` and `{content}`.\n`{current_date}` is optional, depending on the use.", + "type": "string", + "example": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.", + "maxLength": 10000, + "pattern": "(\\{user_question\\}[\\s\\S]*?\\{content\\}|\\{content\\}[\\s\\S]*?\\{user_question\\})" + } + } + } + ], + "title": "AI agent basic text tool", + "x-box-tag": "ai" + }, + "AiAgentBasicTextToolBase": { + "description": "AI agent tool used to handle basic text.", + "type": "object", + "properties": { + "model": { + "description": "The model used for the AI agent for basic text. For specific model values, see the [available models list](g://box-ai/supported-models).", + "type": "string", + "example": "azure__openai__gpt_3_5_turbo_16k" + }, + "num_tokens_for_completion": { + "description": "The number of tokens for completion.", + "type": "integer", + "example": 8400, + "minimum": 1 + }, + "llm_endpoint_params": { + "description": "The parameters for the LLM endpoint specific to OpenAI / Google models.", + "oneOf": [ + { + "$ref": "#/components/schemas/AiLlmEndpointParamsOpenAi" + }, + { + "$ref": "#/components/schemas/AiLlmEndpointParamsGoogle" + } + ] + } + }, + "title": "AI agent basic text tool", + "x-box-tag": "ai" + }, + "AiAgentBasicTextToolTextGen": { + "description": "AI agent tool used to handle basic text.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/AiAgentBasicTextToolBase" + }, + { + "properties": { + "system_message": { + "description": "System messages aim at helping the LLM understand its role and what it is supposed to do.\nThe input for `{current_date}` is optional, depending on the use.", + "type": "string", + "example": "You are a helpful travel assistant specialized in budget travel" + }, + "prompt_template": { + "description": "The prompt template contains contextual information of the request and the user prompt.\n\nWhen using the `prompt_template` parameter, you **must include** input for `{user_question}`.\nInputs for `{current_date}` and `{content}` are optional, depending on the use.", + "type": "string", + "example": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. `{user_question}`", + "maxLength": 10000, + "pattern": "\\{user_question\\}" + } + } + } + ], + "title": "AI agent basic text tool", + "x-box-tag": "ai" + }, + "AiAgentExtract": { + "description": "The AI agent to be used for extraction.", + "type": "object", + "properties": { + "type": { + "description": "The type of AI agent to be used for extraction.", + "type": "string", + "example": "ai_agent_extract", + "enum": [ + "ai_agent_extract" + ], + "nullable": false + }, + "long_text": { + "$ref": "#/components/schemas/AiAgentLongTextTool" + }, + "basic_text": { + "$ref": "#/components/schemas/AiAgentBasicTextTool" + } + }, + "required": [ + "type" + ], + "title": "AI agent for extract requests", + "x-box-resource-id": "ai_agent_extract", + "x-box-tag": "ai" + }, + "AiAgentExtractStructured": { + "description": "The AI agent to be used for structured extraction.", + "type": "object", + "properties": { + "type": { + "description": "The type of AI agent to be used for extraction.", + "type": "string", + "example": "ai_agent_extract_structured", + "enum": [ + "ai_agent_extract_structured" + ], + "nullable": false + }, + "long_text": { + "$ref": "#/components/schemas/AiAgentLongTextTool" + }, + "basic_text": { + "$ref": "#/components/schemas/AiAgentBasicTextTool" + } + }, + "required": [ + "type" + ], + "title": "AI agent for structured extract request", + "x-box-resource-id": "ai_agent_extract_structured", + "x-box-tag": "ai" + }, + "AiAgentLongTextTool": { + "description": "AI agent tool used to to handle longer text.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/AiAgentBasicTextTool" + }, + { + "properties": { + "embeddings": { + "type": "object", + "properties": { + "model": { + "description": "The model used for the AI agent for calculating embeddings.", + "type": "string", + "example": "openai__text_embedding_ada_002" + }, + "strategy": { + "type": "object", + "properties": { + "id": { + "description": "The strategy used for the AI agent for calculating embeddings.", + "type": "string", + "example": "basic" + }, + "num_tokens_per_chunk": { + "description": "The number of tokens per chunk.", + "type": "integer", + "example": 64, + "minimum": 1 + } + } + } + } + } + } + } + ], + "title": "AI agent long text tool", + "x-box-tag": "ai" + }, + "AiAgentLongTextToolTextGen": { + "description": "AI agent tool used to to handle longer text.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/AiAgentBasicTextToolTextGen" + }, + { + "properties": { + "embeddings": { + "type": "object", + "properties": { + "model": { + "description": "The model used for the AI agent for calculating embeddings.", + "type": "string", + "example": "openai__text_embedding_ada_002" + }, + "strategy": { + "type": "object", + "properties": { + "id": { + "description": "The strategy used for the AI agent for calculating embeddings.", + "type": "string", + "example": "basic" + }, + "num_tokens_per_chunk": { + "description": "The number of tokens per chunk.", + "type": "integer", + "example": 64, + "minimum": 1 + } + } + } + } + } + } + } + ], + "title": "AI agent long text tool", + "x-box-tag": "ai" + }, + "AiAgentTextGen": { + "description": "The AI agent used for generating text.", + "type": "object", + "properties": { + "type": { + "description": "The type of AI agent used for generating text.", + "type": "string", + "example": "ai_agent_text_gen", + "enum": [ + "ai_agent_text_gen" + ], + "nullable": false + }, + "basic_gen": { + "$ref": "#/components/schemas/AiAgentBasicGenTool" + } + }, + "required": [ + "type" + ], + "title": "AI agent for text generation requests", + "x-box-resource-id": "ai_agent_text_gen", + "x-box-tag": "ai" + }, + "AiAsk": { + "description": "AI ask request object", + "type": "object", + "properties": { + "mode": { + "description": "The mode specifies if this request is for a single or multiple items. If you select `single_item_qa` the `items` array can have one element only. Selecting `multiple_item_qa` allows you to provide up to 25 items.", + "type": "string", + "example": "multiple_item_qa", + "enum": [ + "multiple_item_qa", + "single_item_qa" + ], + "nullable": false + }, + "prompt": { + "description": "The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters.", + "type": "string", + "example": "What is the value provided by public APIs based on this document?" + }, + "items": { + "description": "The items to be processed by the LLM, often files.\n\n**Note**: Box AI handles documents with text representations up to 1MB in size, or a maximum of 25 files, whichever comes first.\nIf the file size exceeds 1MB, the first 1MB of text representation will be processed.\nIf you set `mode` parameter to `single_item_qa`, the `items` array can have one element only. ", + "type": "array", + "items": { + "$ref": "#/components/schemas/AiItem--Base" + }, + "maxItems": 25, + "minItems": 1, + "uniqueItems": true + }, + "dialogue_history": { + "description": "The history of prompts and answers previously passed to the LLM. This provides additional context to the LLM in generating the response.", + "type": "array", + "items": { + "$ref": "#/components/schemas/AiDialogueHistory" + } + }, + "include_citations": { + "description": "A flag to indicate whether citations should be returned.", + "type": "boolean", + "example": true + }, + "ai_agent": { + "$ref": "#/components/schemas/AiAgentAsk" + } + }, + "required": [ + "prompt", + "items", + "mode" + ], + "title": "AI ask request", + "x-box-tag": "ai" + }, + "AiCitation": { + "description": "The citation of the LLM's answer reference.", + "type": "object", + "properties": { + "content": { + "description": "The specific content from where the answer was referenced.", + "example": "Public APIs are key drivers of innovation and growth.", + "type": "string" + }, + "id": { + "description": "The id of the item.", + "type": "string", + "example": "123" + }, + "type": { + "description": "The type of the item.", + "type": "string", + "example": "file", + "enum": [ + "file" + ] + }, + "name": { + "description": "The name of the item.", + "type": "string", + "example": "The importance of public APIs.pdf" + } + }, + "title": "The citation of the LLM's answer reference" + }, + "AiDialogueHistory": { + "description": "A context object that can hold prior prompts and answers.", + "type": "object", + "properties": { + "prompt": { + "description": "The prompt previously provided by the client and answered by the LLM.", + "type": "string", + "example": "Make my email about public APIs sound more professional." + }, + "answer": { + "description": "The answer previously provided by the LLM.", + "type": "string", + "example": "Here is the first draft of your professional email about public APIs." + }, + "created_at": { + "description": "The ISO date formatted timestamp of when the previous answer to the prompt was created.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + }, + "title": "Dialogue history" + }, + "AiExtract": { + "description": "AI metadata freeform extraction request object", + "type": "object", + "properties": { + "prompt": { + "description": "The prompt provided to a Large Language Model (LLM) in the request. The prompt can be up to 10000 characters long and it can be an XML or a JSON schema.", + "type": "string", + "example": "\\\"fields\\\":[{\\\"type\\\":\\\"string\\\",\\\"key\\\":\\\"name\\\",\\\"displayName\\\":\\\"Name\\\",\\\"description\\\":\\\"The customer name\\\",\\\"prompt\\\":\\\"Name is always the first word in the document\\\"},{\\\"type\\\":\\\"date\\\",\\\"key\\\":\\\"last_contacted_at\\\",\\\"displayName\\\":\\\"Last Contacted At\\\",\\\"description\\\":\\\"When this customer was last contacted at\\\"}]" + }, + "items": { + "description": "The items that LLM will process. Currently, you can use files only.", + "type": "array", + "items": { + "$ref": "#/components/schemas/AiItem--Base" + }, + "maxItems": 1, + "minItems": 1, + "uniqueItems": true + }, + "ai_agent": { + "$ref": "#/components/schemas/AiAgentExtract" + } + }, + "required": [ + "prompt", + "items" + ], + "title": "AI metadata freeform extraction request", + "x-box-tag": "ai" + }, + "AiExtractResponse": { + "description": "AI extract response.\nThe content of this response may vary depending on\nthe requested configuration.", + "type": "object", + "title": "AI extract response", + "x-box-resource-id": "ai_extract_response", + "x-box-tag": "ai" + }, + "AiExtractStructured": { + "description": "AI Extract Structured Request object.", + "type": "object", + "properties": { + "items": { + "description": "The items to be processed by the LLM. Currently you can use files only.", + "type": "array", + "items": { + "$ref": "#/components/schemas/AiItem--Base" + }, + "maxItems": 1, + "minItems": 1, + "uniqueItems": true + }, + "metadata_template": { + "description": "The metadata template containing the fields to extract.\nFor your request to work, you must provide either `metadata_template` or `fields`, but not both.", + "type": "object", + "properties": { + "template_key": { + "description": "The name of the metadata template.", + "type": "string", + "example": "invoiceTemplate" + }, + "type": { + "description": "Value is always `metadata_template`.", + "type": "string", + "example": "metadata_template", + "enum": [ + "metadata_template" + ] + }, + "scope": { + "description": "The scope of the metadata template that can either be global or\nenterprise. \n* The **global** scope is used for templates that are\navailable to any Box enterprise. \n* The **enterprise** scope represents templates created within a specific enterprise,\n containing the ID of that enterprise.", + "type": "string", + "example": "enterprise_12345", + "maxLength": 40 + } + } + }, + "fields": { + "description": "The fields to be extracted from the provided items.\nFor your request to work, you must provide either `metadata_template` or `fields`, but not both.", + "type": "array", + "items": { + "type": "object", + "description": "The fields to be extracted from the provided items.", + "required": [ + "key" + ], + "properties": { + "key": { + "description": "A unique identifier for the field.", + "type": "string", + "example": "name" + }, + "description": { + "description": "A description of the field.", + "type": "string", + "example": "The name of the person." + }, + "displayName": { + "description": "The display name of the field.", + "type": "string", + "example": "Name" + }, + "prompt": { + "description": "The context about the key that may include how to find and format it.", + "type": "string", + "example": "Name is the first and last name from the email address" + }, + "type": { + "description": "The type of the field. It include but is not limited to string, float, date, enum, and multiSelect.", + "type": "string", + "example": "enum" + }, + "options": { + "description": "A list of options for this field. This is most often used in combination with the enum and multiSelect field types.", + "type": "array", + "items": { + "type": "object", + "required": [ + "key" + ], + "properties": { + "key": { + "description": "A unique identifier for the field.", + "type": "string", + "example": "First Name" + } + } + }, + "example": [ + { + "key": "First Name" + }, + { + "key": "Last Name" + } + ] + } + } + }, + "minItems": 1, + "uniqueItems": true + }, + "ai_agent": { + "$ref": "#/components/schemas/AiAgentExtractStructured" + } + }, + "required": [ + "items" + ], + "title": "AI Extract Structured Request", + "x-box-tag": "ai" + }, + "AiItem--Base": { + "description": "The item to be processed by the LLM.", + "type": "object", + "properties": { + "id": { + "description": "The ID of the file.", + "type": "string", + "example": "123" + }, + "type": { + "description": "The type of the item. Currently the value can be `file` only.", + "type": "string", + "example": "file", + "enum": [ + "file" + ] + }, + "content": { + "description": "The content of the item, often the text representation.", + "example": "This is file content.", + "type": "string" + } + }, + "required": [ + "id", + "type" + ], + "title": "AI Item (Base)", + "x-box-variant": "base", + "x-box-variants": [ + "base" + ] + }, + "AiLlmEndpointParamsGoogle": { + "description": "AI LLM endpoint params Google object", + "type": "object", + "properties": { + "type": { + "description": "The type of the AI LLM endpoint params object for Google.\nThis parameter is **required**.", + "type": "string", + "example": "google_params", + "enum": [ + "google_params" + ], + "nullable": false + }, + "temperature": { + "description": "The temperature is used for sampling during response generation, which occurs when `top-P` and `top-K` are applied. Temperature controls the degree of randomness in the token selection.", + "type": "number", + "example": 0, + "maximum": 2, + "minimum": 0, + "nullable": true + }, + "top_p": { + "description": "`Top-P` changes how the model selects tokens for output. Tokens are selected from the most (see `top-K`) to least probable until the sum of their probabilities equals the `top-P` value.", + "type": "number", + "example": 1, + "maximum": 2, + "minimum": 0.1, + "nullable": true + }, + "top_k": { + "description": "`Top-K` changes how the model selects tokens for output. A `top-K` of 1 means the next selected token is\nthe most probable among all tokens in the model's vocabulary (also called greedy decoding),\nwhile a `top-K` of 3 means that the next token is selected from among the three most probable tokens by using temperature.", + "type": "number", + "example": 1, + "maximum": 2, + "minimum": 0.1, + "nullable": true + } + }, + "required": [ + "type" + ], + "title": "AI LLM endpoint params Google", + "x-box-resource-id": "ai_llm_endpoint_params_google" + }, + "AiLlmEndpointParamsOpenAi": { + "description": "AI LLM endpoint params OpenAI object.", + "type": "object", + "properties": { + "type": { + "description": "The type of the AI LLM endpoint params object for OpenAI.\nThis parameter is **required**.", + "type": "string", + "example": "openai_params", + "enum": [ + "openai_params" + ], + "nullable": false + }, + "temperature": { + "description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, \nwhile lower values like 0.2 will make it more focused and deterministic. \nWe generally recommend altering this or `top_p` but not both.", + "type": "number", + "example": 0, + "maximum": 2, + "minimum": 0, + "nullable": true + }, + "top_p": { + "description": "An alternative to sampling with temperature, called nucleus sampling, where the model considers the results \nof the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability \nmass are considered. We generally recommend altering this or temperature but not both.", + "type": "number", + "example": 1, + "maximum": 1, + "minimum": 0.1, + "nullable": true + }, + "frequency_penalty": { + "description": "A number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the \ntext so far, decreasing the model's likelihood to repeat the same line verbatim.", + "type": "number", + "example": 1.5, + "maximum": 2, + "minimum": -2, + "nullable": true + }, + "presence_penalty": { + "description": "A number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.", + "type": "number", + "example": 1.5, + "maximum": 2, + "minimum": -2, + "nullable": true + }, + "stop": { + "description": "Up to 4 sequences where the API will stop generating further tokens.", + "type": "string", + "example": "<|im_end|>", + "nullable": true + } + }, + "required": [ + "type" + ], + "title": "AI LLM endpoint params OpenAI", + "x-box-resource-id": "ai_llm_endpoint_params_openai" + }, + "AiResponse": { + "description": "AI response", + "type": "object", + "properties": { + "answer": { + "description": "The answer provided by the LLM.", + "type": "string", + "example": "Public APIs are important because of key and important reasons." + }, + "created_at": { + "description": "The ISO date formatted timestamp of when the answer to the prompt was created.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "completion_reason": { + "description": "The reason the response finishes.", + "type": "string", + "example": "done" + } + }, + "required": [ + "answer", + "created_at" + ], + "title": "AI response", + "x-box-resource-id": "ai_response", + "x-box-tag": "ai", + "x-box-variant": "standard", + "x-box-variants": [ + "standard", + "full" + ] + }, + "AiResponse--Full": { + "description": "AI ask response", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/AiResponse" + }, + { + "properties": { + "citations": { + "description": "The citations of the LLM's answer reference.", + "type": "array", + "items": { + "$ref": "#/components/schemas/AiCitation" + } + } + } + } + ], + "required": [ + "answer", + "created_at" + ], + "title": "AI response (Full)", + "x-box-resource-id": "ai_response--full", + "x-box-tag": "ai", + "x-box-variant": "full", + "x-box-variants": [ + "standard", + "full" + ] + }, + "AiTextGen": { + "description": "AI text gen request object", + "type": "object", + "properties": { + "prompt": { + "description": "The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters.", + "type": "string", + "example": "Write an email to a client about the importance of public APIs." + }, + "items": { + "description": "The items to be processed by the LLM, often files.\nThe array can include **exactly one** element.\n\n**Note**: Box AI handles documents with text representations up to 1MB in size.\nIf the file size exceeds 1MB, the first 1MB of text representation will be processed.", + "type": "array", + "items": { + "required": [ + "id", + "type" + ], + "type": "object", + "description": "The item to be processed by the LLM.", + "properties": { + "id": { + "description": "The ID of the item.", + "type": "string", + "example": "123" + }, + "type": { + "description": "The type of the item.", + "type": "string", + "example": "file", + "enum": [ + "file" + ] + }, + "content": { + "description": "The content to use as context for generating new text or editing existing text.", + "example": "This is file content that is relevant to the text gen request.", + "type": "string" + } + } + }, + "maxItems": 1, + "minItems": 1, + "uniqueItems": true + }, + "dialogue_history": { + "description": "The history of prompts and answers previously passed to the LLM. This parameter provides the additional context to the LLM when generating the response.", + "type": "array", + "items": { + "$ref": "#/components/schemas/AiDialogueHistory" + } + }, + "ai_agent": { + "$ref": "#/components/schemas/AiAgentTextGen" + } + }, + "required": [ + "prompt", + "items" + ], + "title": "AI text gen request", + "x-box-tag": "ai" + }, + "AppItem": { + "description": "An app item represents an content object owned by an application. It can\ngroup files and folders together from different paths. That set can be shared\nvia a collaboration.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this app item.", + "type": "string", + "example": "12345678" + }, + "type": { + "description": "`app_item`", + "type": "string", + "example": "app_item", + "enum": [ + "app_item" + ] + }, + "application_type": { + "description": "The type of the app that owns this app item.", + "type": "string", + "example": "hubs" + } + }, + "required": [ + "id", + "type", + "application_type" + ], + "title": "App item", + "x-box-resource-id": "app_item", + "x-box-tag": "app_item_associations" + }, + "AppItemAssociation": { + "description": "An app item association represents an association between a file or\nfolder and an app item. Associations between a folder and an app item\ncascade down to all descendants of the folder.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this app item association.", + "type": "string", + "example": "12345678", + "nullable": false + }, + "type": { + "description": "`app_item_association`", + "type": "string", + "example": "app_item_association", + "enum": [ + "app_item_association" + ], + "nullable": false + }, + "app_item": { + "allOf": [ + { + "$ref": "#/components/schemas/AppItem" + }, + { + "description": "The app item which is associated with the file or folder." + } + ], + "nullable": false + }, + "item": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/File--Base" + }, + { + "$ref": "#/components/schemas/Folder--Base" + }, + { + "$ref": "#/components/schemas/WebLink--Base" + } + ] + }, + { + "description": "The file or folder which is associated with the app item." + } + ], + "nullable": false + } + }, + "required": [ + "id", + "type", + "app_item", + "item" + ], + "title": "App item association", + "x-box-resource-id": "app_item_association", + "x-box-tag": "app_item_associations" + }, + "AppItemAssociations": { + "description": "A list of app item associations", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AppItemAssociation" + } + } + } + } + ], + "title": "App item associations", + "x-box-resource-id": "app_item_associations", + "x-box-tag": "app_item_associations" + }, + "AppItemEventSource": { + "description": "The AppItem that triggered an event in the event stream.", + "type": "object", + "properties": { + "id": { + "description": "The id of the `AppItem`", + "type": "string", + "example": "6374669741" + }, + "type": { + "description": "The type of the source that this event represents. Can only be `app_item`.\n", + "type": "string", + "example": "app_item", + "enum": [ + "app_item" + ], + "nullable": false + }, + "app_item_type": { + "description": "The type of the `AppItem`", + "type": "string", + "example": "hubs" + }, + "user": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user that triggered the event." + } + ] + }, + "group": { + "allOf": [ + { + "$ref": "#/components/schemas/Group--Mini" + }, + { + "description": "The group that triggered the event." + } + ] + } + }, + "required": [ + "id", + "type", + "app_item_type" + ], + "title": "AppItem event source", + "x-box-resource-id": "app_item_event_source" + }, + "Classification": { + "description": "An instance of the classification metadata template, containing\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.", + "type": "object", + "properties": { + "Box__Security__Classification__Key": { + "description": "The name of the classification applied to the item.", + "type": "string", + "example": "Sensitive" + }, + "$parent": { + "description": "The identifier of the item that this metadata instance\nhas been attached to. This combines the `type` and the `id`\nof the parent in the form `{type}_{id}`.", + "type": "string", + "example": "folder_59449484661," + }, + "$template": { + "description": "`securityClassification-6VMVochwUWo`", + "type": "string", + "example": "securityClassification-6VMVochwUWo", + "enum": [ + "securityClassification-6VMVochwUWo" + ] + }, + "$scope": { + "description": "The scope of the enterprise that this classification has been\napplied for.\n\nThis will be in the format `enterprise_{enterprise_id}`.", + "type": "string", + "example": "enterprise_27335" + }, + "$version": { + "description": "The version of the metadata instance. This version starts at 0 and\nincreases every time a classification is updated.", + "type": "integer", + "example": 1 + }, + "$type": { + "description": "The unique ID of this classification instance. This will be include\nthe name of the classification template and a unique ID.", + "type": "string", + "example": "securityClassification-6VMVochwUWo-fd31537a-0f95-4d86-9f2b-5974a29978f8" + }, + "$typeVersion": { + "description": "The version of the metadata template. This version starts at 0 and\nincreases every time the template is updated. This is mostly for internal\nuse.", + "type": "number", + "example": 5 + }, + "$canEdit": { + "description": "Whether an end user can change the classification.", + "type": "boolean", + "example": true + } + }, + "title": "Classification", + "x-box-resource-id": "classification", + "x-box-tag": "classifications" + }, + "ClassificationTemplate": { + "description": "A metadata template that holds the security classifications\ndefined by an enterprise.", + "type": "object", + "properties": { + "id": { + "description": "The ID of the classification template.", + "type": "string", + "example": "58063d82-4128-7b43-bba9-92f706befcdf" + }, + "type": { + "description": "`metadata_template`", + "type": "string", + "example": "metadata_template", + "enum": [ + "metadata_template" + ], + "nullable": false + }, + "scope": { + "description": "The scope of the classification template. This is in the format\n`enterprise_{id}` where the `id` is the enterprise ID.", + "type": "string", + "example": "enterprise_123456" + }, + "templateKey": { + "description": "`securityClassification-6VMVochwUWo`", + "type": "string", + "example": "securityClassification-6VMVochwUWo", + "enum": [ + "securityClassification-6VMVochwUWo" + ] + }, + "displayName": { + "description": "The name of this template as shown in web and mobile interfaces.", + "type": "string", + "example": "Classification", + "enum": [ + "Classification" + ] + }, + "hidden": { + "description": "Determines if the\ntemplate is always available in web and mobile interfaces.", + "type": "boolean", + "example": false + }, + "copyInstanceOnItemCopy": { + "description": "Determines if \nclassifications are\ncopied along when the file or folder is\ncopied.", + "type": "boolean", + "example": true + }, + "fields": { + "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.", + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "type", + "key", + "displayName", + "options" + ], + "description": "The metadata template field that represents the available\nclassifications.", + "properties": { + "id": { + "description": "The unique ID of the field.", + "type": "string", + "example": "822227e0-47a5-921b-88a8-494760b2e6d2" + }, + "type": { + "description": "The array item type.", + "type": "string", + "example": "enum", + "enum": [ + "enum" + ] + }, + "key": { + "description": "Defines classifications \navailable in the enterprise.", + "type": "string", + "example": "Box__Security__Classification__Key", + "enum": [ + "Box__Security__Classification__Key" + ] + }, + "displayName": { + "description": "`Classification`", + "type": "string", + "example": "Classification", + "enum": [ + "Classification" + ] + }, + "hidden": { + "description": "Classifications are always visible to web and mobile users.", + "type": "boolean", + "example": false + }, + "options": { + "description": "A list of classifications available in this enterprise.", + "type": "array", + "items": { + "required": [ + "key", + "id" + ], + "type": "object", + "description": "A single classification available in this enterprise.", + "properties": { + "id": { + "description": "The unique ID of this classification.", + "type": "string", + "example": "46aea176-3483-4431-856c-6b5b13d1cc50" + }, + "key": { + "description": "The display name and key for this classification.", + "type": "string", + "example": "Sensitive" + }, + "staticConfig": { + "description": "Additional information about the classification.", + "type": "object", + "properties": { + "classification": { + "description": "Additional information about the classification.\n\nThis is not an exclusive list of properties, and\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.", + "type": "object", + "properties": { + "classificationDefinition": { + "description": "A longer description of the classification.", + "type": "string", + "example": "Sensitive information" + }, + "colorID": { + "description": "An internal Box identifier used to assign a color to\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", + "type": "integer", + "format": "int64", + "example": 4 + } + } + } + } + } + } + }, + "minItems": 1 + } + } + }, + "maxItems": 1, + "minItems": 1 + } + }, + "required": [ + "id", + "type", + "scope", + "displayName", + "fields", + "templateKey" + ], + "title": "Classification Template", + "x-box-resource-id": "classification_template", + "x-box-tag": "classifications" + }, + "ClientError": { + "description": "A generic error", + "type": "object", + "properties": { + "type": { + "description": "error", + "type": "string", + "example": "error", + "enum": [ + "error" + ], + "nullable": false + }, + "status": { + "description": "The HTTP status of the response.", + "type": "integer", + "format": "int32", + "example": 400, + "nullable": false + }, + "code": { + "description": "A Box-specific error code", + "type": "string", + "example": "item_name_invalid", + "enum": [ + "created", + "accepted", + "no_content", + "redirect", + "not_modified", + "bad_request", + "unauthorized", + "forbidden", + "not_found", + "method_not_allowed", + "conflict", + "precondition_failed", + "too_many_requests", + "internal_server_error", + "unavailable", + "item_name_invalid", + "insufficient_scope" + ] + }, + "message": { + "description": "A short message describing the error.", + "type": "string", + "example": "Method Not Allowed", + "nullable": false + }, + "context_info": { + "description": "A free-form object that contains additional context\nabout the error. The possible fields are defined on\na per-endpoint basis. `message` is only one example.", + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "help_url": { + "description": "A URL that links to more information about why this error occurred.", + "type": "string", + "example": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/", + "nullable": false + }, + "request_id": { + "description": "A unique identifier for this response, which can be used\nwhen contacting Box support.", + "type": "string", + "example": "abcdef123456", + "nullable": false + } + }, + "title": "Client error", + "x-box-resource-id": "client_error" + }, + "Collaboration": { + "description": "Collaborations define access permissions for users and groups to files and\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.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this collaboration.", + "type": "string", + "example": "12345678" + }, + "type": { + "description": "`collaboration`", + "type": "string", + "example": "collaboration", + "enum": [ + "collaboration" + ] + }, + "item": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/File" + }, + { + "$ref": "#/components/schemas/Folder" + }, + { + "$ref": "#/components/schemas/WebLink" + } + ] + }, + { + "description": "The file or folder to which access is granted. The field is\n`null` when the collaboration `status` is `pending` or the\ncollaboration is created on an app item (see `app_item` field)." + } + ], + "nullable": true + }, + "app_item": { + "allOf": [ + { + "$ref": "#/components/schemas/AppItem" + }, + { + "description": "An `app_item` to which access is granted. The field is `null`\nwhen the collaboration is created on an item (see `item`\nfield), or the `app_item` is inaccessible. The role cascades\nto all items associated with the `app_item`." + } + ], + "nullable": true + }, + "accessible_by": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/User--Collaborations" + }, + { + "$ref": "#/components/schemas/Group--Mini" + } + ] + }, + { + "description": "The user or group that is granted access." + } + ] + }, + "invite_email": { + "description": "The email address used to invite an unregistered collaborator, if\nthey are not a registered user.", + "type": "string", + "example": "john@example.com", + "nullable": true + }, + "role": { + "description": "The level of access granted.", + "type": "string", + "example": "editor", + "enum": [ + "editor", + "viewer", + "previewer", + "uploader", + "previewer uploader", + "viewer uploader", + "co-owner", + "owner" + ] + }, + "expires_at": { + "description": "When the collaboration will expire, or `null` if no expiration\ndate is set.", + "type": "string", + "format": "date-time", + "example": "2012-12-26T10:53:43-08:00", + "nullable": true + }, + "is_access_only": { + "description": "If set to `true`, collaborators have access to\nshared items, but such items won't be visible in the\nAll Files list. Additionally, collaborators won't\nsee the the path to the root folder for the\nshared item.", + "type": "boolean", + "example": true + }, + "status": { + "description": "The status of the collaboration invitation. If the status\nis `pending`, `login` and `name` return an empty string.", + "type": "string", + "example": "accepted", + "enum": [ + "accepted", + "pending", + "rejected" + ] + }, + "acknowledged_at": { + "description": "When the `status` of the collaboration object changed to\n`accepted` or `rejected`.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:55:20-08:00" + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Collaborations" + }, + { + "description": "The user who created the collaboration object." + }, + { + "example": [ + { + "id": 33224412 + }, + { + "type": "user" + }, + { + "login": "dylan@example.com" + }, + { + "name": "Dylan Smith" + } + ] + } + ] + }, + "created_at": { + "description": "When the collaboration object was created.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When the collaboration object was last modified.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "acceptance_requirements_status": { + "type": "object", + "properties": { + "terms_of_service_requirement": { + "type": "object", + "properties": { + "is_accepted": { + "description": "Whether or not the terms of service have been accepted. The\nfield is `null` when there is no terms of service required.", + "type": "boolean", + "example": true, + "nullable": true + }, + "terms_of_service": { + "allOf": [ + { + "$ref": "#/components/schemas/TermsOfService--Base" + }, + { + "description": "The terms of service that must be accepted before the\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": { + "description": "Whether or not the enterprise that owns the content requires\na strong password to collaborate on the content.", + "type": "boolean", + "example": true + }, + "user_has_strong_password": { + "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.", + "type": "boolean", + "example": true, + "nullable": true + } + } + }, + "two_factor_authentication_requirement": { + "type": "object", + "properties": { + "enterprise_has_two_factor_auth_enabled": { + "description": "Whether or not the enterprise that owns the content requires\ntwo-factor authentication to be enabled in order to\ncollaborate on the content.", + "type": "boolean", + "example": true + }, + "user_has_two_factor_authentication_enabled": { + "description": "Whether or not the user has two-factor authentication\nenabled. The field is `null` when two-factor\nauthentication is not required.", + "type": "boolean", + "example": true, + "nullable": true + } + } + } + } + } + }, + "required": [ + "id", + "type" + ], + "title": "Collaboration", + "x-box-resource-id": "collaboration", + "x-box-tag": "user_collaborations" + }, + "CollaborationAllowlistEntries": { + "description": "A list of allowed domains for collaboration.", + "type": "object", + "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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of allowed collaboration domains", + "type": "array", + "items": { + "$ref": "#/components/schemas/CollaborationAllowlistEntry" + } + } + } + } + ], + "title": "Allowed collaboration domains", + "x-box-resource-id": "collaboration_allowlist_entries", + "x-box-tag": "collaboration_allowlist_entries" + }, + "CollaborationAllowlistEntry": { + "description": "An entry that describes an approved domain for which users can collaborate\nwith files and folders in your enterprise or vice versa.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this entry", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`collaboration_whitelist_entry`", + "type": "string", + "example": "collaboration_whitelist_entry", + "enum": [ + "collaboration_whitelist_entry" + ] + }, + "domain": { + "description": "The whitelisted domain", + "type": "string", + "example": "example.com" + }, + "direction": { + "description": "The direction of the collaborations to allow.", + "type": "string", + "example": "both", + "enum": [ + "inbound", + "outbound", + "both" + ] + }, + "enterprise": { + "allOf": [ + { + "title": "Enterprise", + "type": "object", + "description": "A representation of a Box enterprise", + "properties": { + "id": { + "description": "The unique identifier for this enterprise.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`enterprise`", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise" + ] + }, + "name": { + "description": "The name of the enterprise", + "type": "string", + "example": "Acme Inc." + } + } + }, + { + "description": "The enterprise this list is applied to" + } + ] + }, + "created_at": { + "description": "The time the entry was created at", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + }, + "title": "Allowed collaboration domain", + "x-box-resource-id": "collaboration_allowlist_entry", + "x-box-tag": "collaboration_allowlist_entries" + }, + "CollaborationAllowlistExemptTarget": { + "description": "The user that is exempt from any of the restrictions\nimposed by the list of allowed collaboration domains for this enterprise.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this exemption", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`collaboration_whitelist_exempt_target`", + "type": "string", + "example": "collaboration_whitelist_exempt_target", + "enum": [ + "collaboration_whitelist_exempt_target" + ] + }, + "enterprise": { + "allOf": [ + { + "title": "Enterprise", + "type": "object", + "description": "A representation of a Box enterprise", + "properties": { + "id": { + "description": "The unique identifier for this enterprise.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`enterprise`", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise" + ] + }, + "name": { + "description": "The name of the enterprise", + "type": "string", + "example": "Acme Inc." + } + } + }, + { + "description": "The enterprise this entry belongs to" + } + ] + }, + "user": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user that has been exempt" + } + ] + }, + "created_at": { + "description": "The time the entry was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "The time the entry was modified", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + }, + "title": "Allowed collaboration domains user exemption", + "x-box-resource-id": "collaboration_allowlist_exempt_target", + "x-box-tag": "collaboration_allowlist_exempt_targets" + }, + "CollaborationAllowlistExemptTargets": { + "description": "A list of users exempt from any of the restrictions\nimposed by the list of allowed collaboration domains for this enterprise.", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of users exempt from any of the restrictions\nimposed by the list of allowed collaboration domains\nfor this enterprise.", + "type": "array", + "items": { + "$ref": "#/components/schemas/CollaborationAllowlistExemptTarget" + } + } + } + } + ], + "title": "Allowed collaboration domains user exemptions", + "x-box-resource-id": "collaboration_allowlist_exempt_targets", + "x-box-tag": "collaboration_allowlist_exempt_targets" + }, + "Collaborations": { + "description": "A list of collaborations", + "type": "object", + "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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "type": "object", + "description": "The part of an API response that describes pagination", + "properties": { + "total_count": { + "description": "One greater than the offset of the last entry in the entire collection.\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", + "example": 5000 + }, + "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", + "example": 1000 + }, + "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", + "example": 2000 + }, + "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", + "example": "type" + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "ASC", + "enum": [ + "ASC", + "DESC" + ] + } + } + } + } + } + }, + { + "properties": { + "entries": { + "description": "A list of collaborations", + "type": "array", + "items": { + "$ref": "#/components/schemas/Collaboration" + } + } + } + } + ], + "title": "Collaborations", + "x-box-resource-id": "collaborations", + "x-box-tag": "user_collaborations" + }, + "CollaboratorVariable": { + "description": "A collaborator\nobject. Allows to\nspecify a list of user\nID's that are affected\nby the workflow result.", + "type": "object", + "properties": { + "type": { + "description": "Collaborator\nobject type.\n", + "type": "string", + "example": "variable", + "enum": [ + "variable" + ] + }, + "variable_type": { + "description": "Variable type \nfor the Collaborator\nobject.\n", + "type": "string", + "example": "user_list", + "enum": [ + "user_list" + ] + }, + "variable_value": { + "description": "A list of user IDs.", + "type": "array", + "items": { + "type": "object", + "required": [ + "type", + "id" + ], + "description": "User variable used\nin workflow outcomes.", + "properties": { + "type": { + "description": "The object type.", + "type": "string", + "example": "user", + "enum": [ + "user" + ] + }, + "id": { + "description": "User's ID.", + "type": "string", + "example": "636281" + } + } + } + } + }, + "required": [ + "type", + "variable_type", + "variable_value" + ], + "title": "Collaborator variable" + }, + "Collection": { + "description": "A collection of items, including files and folders.\n\nCurrently, the only collection available\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.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this collection.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`collection`", + "type": "string", + "example": "collection", + "enum": [ + "collection" + ] + }, + "name": { + "description": "The name of the collection.", + "type": "string", + "example": "Favorites", + "enum": [ + "Favorites" + ] + }, + "collection_type": { + "description": "The type of the collection. This is used to\ndetermine the proper visual treatment for\ncollections.", + "type": "string", + "example": "favorites", + "enum": [ + "favorites" + ] + } + }, + "title": "Collection", + "x-box-resource-id": "collection", + "x-box-tag": "collections" + }, + "Collections": { + "description": "A list of collections", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes pagination", + "properties": { + "total_count": { + "description": "One greater than the offset of the last entry in the entire collection.\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", + "example": 5000 + }, + "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", + "example": 1000 + }, + "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", + "example": 2000 + }, + "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", + "example": "type" + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "ASC", + "enum": [ + "ASC", + "DESC" + ] + } + } + } + } + } + }, + { + "properties": { + "entries": { + "description": "A list of collections", + "type": "array", + "items": { + "$ref": "#/components/schemas/Collection" + } + } + } + } + ], + "title": "Collections", + "x-box-resource-id": "collections", + "x-box-tag": "collections" + }, + "Comment": { + "description": "Standard representation of a comment.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Comment--Base" + }, + { + "properties": { + "is_reply_comment": { + "description": "Whether or not this comment is a reply to another\ncomment", + "type": "boolean", + "example": true + }, + "message": { + "description": "The text of the comment, as provided by the user", + "type": "string", + "example": "@Aaron Levie these tigers are cool!" + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "A mini user object representing the author of the\ncomment" + } + ] + }, + "created_at": { + "description": "The time this comment was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "The time this comment was last modified", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "item": { + "allOf": [ + { + "title": "Reference", + "description": "The bare basic reference for an object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this object", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type for this object", + "type": "string", + "example": "file" + } + } + }, + { + "description": "The file this comment was placed on" + } + ] + } + } + } + ], + "title": "Comment", + "x-box-resource-id": "comment", + "x-box-variant": "standard" + }, + "Comment--Base": { + "description": "Base representation of a comment.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this comment.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`comment`", + "type": "string", + "example": "comment", + "enum": [ + "comment" + ] + } + }, + "title": "Comment (Base)", + "x-box-resource-id": "comment--base", + "x-box-tag": "comments", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard", + "full" + ] + }, + "Comment--Full": { + "description": "Comments are messages created on files. Comments\ncan be made independently or created as responses to other\ncomments", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Comment" + }, + { + "properties": { + "tagged_message": { + "description": "The string representing the comment text with\n@mentions included. @mention format is @[id:username]\nwhere `id` is user's Box ID and `username` is\ntheir display name.", + "type": "string", + "example": "@[1234567:Aaron Levie] these tigers are cool!" + } + } + } + ], + "title": "Comment (Full)", + "x-box-resource-id": "comment--full", + "x-box-variant": "full" + }, + "Comments": { + "description": "A list of comments", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes pagination", + "properties": { + "total_count": { + "description": "One greater than the offset of the last entry in the entire collection.\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", + "example": 5000 + }, + "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", + "example": 1000 + }, + "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", + "example": 2000 + }, + "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", + "example": "type" + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "ASC", + "enum": [ + "ASC", + "DESC" + ] + } + } + } + } + } + }, + { + "properties": { + "entries": { + "description": "A list of comments", + "type": "array", + "items": { + "$ref": "#/components/schemas/Comment--Full" + } + } + } + } + ], + "title": "Comments", + "x-box-resource-id": "comments", + "x-box-tag": "comments" + }, + "CompletionRuleVariable": { + "description": "A completion\nrule object. Determines\nif an action should be completed\nby all or any assignees.", + "type": "object", + "properties": { + "type": { + "description": "Completion\nRule object type.\n", + "type": "string", + "example": "variable", + "enum": [ + "variable" + ] + }, + "variable_type": { + "description": "Variable type\nfor the Completion\nRule object.\n", + "type": "string", + "example": "task_completion_rule", + "enum": [ + "task_completion_rule" + ] + }, + "variable_value": { + "description": "Variable\nvalues for a completion\nrule.\n", + "type": "string", + "example": "all_assignees", + "enum": [ + "all_assignees", + "any_assignees" + ] + } + }, + "required": [ + "type", + "variable_type", + "variable_value" + ], + "title": "Completion rule variable" + }, + "ConflictError": { + "description": "The error that occurs when a file can not be created due\nto a conflict.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/ClientError" + }, + { + "properties": { + "context_info": { + "type": "object", + "properties": { + "conflicts": { + "description": "A list of the file conflicts that caused this error.", + "type": "array", + "items": { + "$ref": "#/components/schemas/FileConflict" + } + } + } + } + } + } + ], + "title": "Conflict error", + "x-box-resource-id": "conflict_error", + "x-box-tag": "uploads" + }, + "DevicePinner": { + "description": "Device pins allow enterprises to control what devices can\nuse native Box applications.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this device pin.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`device_pinner`", + "type": "string", + "example": "device_pinner", + "enum": [ + "device_pinner" + ] + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user that the device pin belongs to" + } + ] + }, + "product_name": { + "description": "The type of device being pinned", + "type": "string", + "example": "iPad" + } + }, + "title": "Device pinner", + "x-box-resource-id": "device_pinner", + "x-box-tag": "device_pinners" + }, + "DevicePinners": { + "description": "A list of device pins", + "type": "object", + "properties": { + "entries": { + "description": "A list of device pins", + "type": "array", + "items": { + "$ref": "#/components/schemas/DevicePinner" + } + }, + "limit": { + "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed.", + "type": "integer", + "format": "int64", + "example": 200, + "default": 100 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "integer", + "format": "int64", + "example": 3000 + }, + "order": { + "description": "The order by which items are returned.", + "type": "array", + "items": { + "type": "object", + "description": "The order in which a pagination is ordered", + "properties": { + "by": { + "description": "The field that is ordered by", + "type": "string", + "example": "id", + "enum": [ + "id" + ] + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "asc", + "enum": [ + "asc", + "desc" + ] + } + } + } + } + }, + "title": "Device pinners", + "x-box-resource-id": "device_pinners", + "x-box-tag": "device_pinners" + }, + "EmailAlias": { + "description": "An email alias for a user.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this object", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`email_alias`", + "type": "string", + "example": "email_alias", + "enum": [ + "email_alias" + ] + }, + "email": { + "description": "The email address", + "type": "string", + "example": "alias@example.com" + }, + "is_confirmed": { + "description": "Whether the email address has been confirmed", + "type": "boolean", + "example": true + } + }, + "title": "Email alias", + "x-box-resource-id": "email_alias", + "x-box-tag": "email_aliases" + }, + "EmailAliases": { + "description": "A list of email aliases", + "type": "object", + "properties": { + "total_count": { + "description": "The number of email aliases.", + "type": "integer", + "format": "int64", + "example": 5000 + }, + "entries": { + "description": "A list of email aliases", + "type": "array", + "items": { + "$ref": "#/components/schemas/EmailAlias" + } + } + }, + "title": "Email aliases", + "x-box-resource-id": "email_aliases", + "x-box-tag": "email_aliases" + }, + "Enterprise--Base": { + "description": "A mini representation of a enterprise, used when\nnested within another resource.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this enterprise", + "type": "string", + "example": "1910967" + }, + "type": { + "description": "`enterprise`", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise" + ], + "nullable": false + } + }, + "title": "Enterprise (Base)", + "x-box-resource-id": "enterprise--base", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard", + "full" + ] + }, + "Event": { + "description": "The description of an event that happened within Box", + "type": "object", + "properties": { + "type": { + "description": "`event`", + "type": "string", + "example": "event" + }, + "created_at": { + "description": "When the event object was created", + "type": "string", + "format": "date-time", + "example": "2022-12-12T10:53:43-08:00" + }, + "recorded_at": { + "description": "When the event object was recorded in database", + "type": "string", + "format": "date-time", + "example": "2022-12-12T10:54:43-08:00" + }, + "event_id": { + "description": "The ID of the event object. You can use this to detect duplicate events", + "type": "string", + "example": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83" + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user that performed the action represented by the event.\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", + "example": "FILE_MARKED_MALICIOUS", + "type": "string", + "description": "An event type that can trigger an event", + "enum": [ + "ACCESS_GRANTED", + "ACCESS_REVOKED", + "ADD_DEVICE_ASSOCIATION", + "ADD_LOGIN_ACTIVITY_DEVICE", + "ADMIN_LOGIN", + "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_EMAIL_SEND", + "ITEM_MAKE_CURRENT_VERSION", + "ITEM_MODIFY", + "ITEM_MOVE", + "ITEM_OPEN", + "ITEM_PREVIEW", + "ITEM_RENAME", + "ITEM_SHARED", + "ITEM_SHARED_CREATE", + "ITEM_SHARED_UNSHARE", + "ITEM_SHARED_UPDATE", + "ITEM_SYNC", + "ITEM_TRASH", + "ITEM_UNDELETE_VIA_TRASH", + "ITEM_UNSYNC", + "ITEM_UPLOAD", + "LEGAL_HOLD_ASSIGNMENT_CREATE", + "LEGAL_HOLD_ASSIGNMENT_DELETE", + "LEGAL_HOLD_POLICY_CREATE", + "LEGAL_HOLD_POLICY_DELETE", + "LEGAL_HOLD_POLICY_UPDATE", + "LOCK", + "LOCK_CREATE", + "LOCK_DESTROY", + "LOGIN", + "MASTER_INVITE_ACCEPT", + "MASTER_INVITE_REJECT", + "METADATA_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", + "SHARED_LINK_SEND", + "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", + "SHIELD_SHARED_LINK_ACCESS_BLOCKED", + "SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_CREATE", + "SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_UPDATE", + "SIGN_DOCUMENT_ASSIGNED", + "SIGN_DOCUMENT_CANCELLED", + "SIGN_DOCUMENT_COMPLETED", + "SIGN_DOCUMENT_CONVERTED", + "SIGN_DOCUMENT_CREATED", + "SIGN_DOCUMENT_DECLINED", + "SIGN_DOCUMENT_EXPIRED", + "SIGN_DOCUMENT_SIGNED", + "SIGN_DOCUMENT_VIEWED_BY_SIGNED", + "SIGNER_DOWNLOADED", + "SIGNER_FORWARDED", + "STORAGE_EXPIRATION", + "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": { + "description": "The session of the user that performed the action. Not all events will\npopulate this attribute.", + "type": "string", + "example": "70090280850c8d2a1933c1" + }, + "source": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/User" + }, + { + "$ref": "#/components/schemas/EventSource" + }, + { + "$ref": "#/components/schemas/File" + }, + { + "$ref": "#/components/schemas/Folder" + }, + { + "$ref": "#/components/schemas/GenericSource" + }, + { + "$ref": "#/components/schemas/AppItemEventSource" + } + ] + }, + { + "description": "The resource that triggered this event. For more information,\ncheck out the guide on event triggers." + } + ] + }, + "additional_details": { + "description": "This object provides additional information about the event if available.\n\nThis can include how a user performed an event as well as additional\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.", + "type": "object", + "example": { + "key": "value" + } + } + }, + "title": "Event", + "x-box-resource-id": "event", + "x-box-tag": "events" + }, + "EventSource": { + "description": "The source file or folder that triggered an event in\nthe event stream.", + "type": "object", + "properties": { + "item_type": { + "description": "The type of the item that the event\nrepresents. Can be `file` or `folder`.\n", + "type": "string", + "example": "file", + "enum": [ + "file", + "folder" + ], + "nullable": false + }, + "item_id": { + "description": "The unique identifier that represents the\nitem.\n", + "type": "string", + "example": "560284318361", + "nullable": false + }, + "item_name": { + "description": "The name of the item.\n", + "type": "string", + "example": "report.pdf", + "nullable": false + }, + "classification": { + "description": "The object containing classification information for the item that\ntriggered the event. This field will not appear if the item does not\nhave a classification set.", + "type": "object", + "properties": { + "name": { + "description": "The classification's name", + "type": "string", + "example": "Top Secret" + } + } + }, + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the\nroot folder or the trash folder." + } + ], + "nullable": true + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who owns this item." + }, + { + "nullable": false + } + ] + } + }, + "required": [ + "item_type", + "item_id", + "item_name" + ], + "title": "Event source", + "x-box-resource-id": "event_source" + }, + "Events": { + "description": "A list of event objects", + "type": "object", + "properties": { + "chunk_size": { + "description": "The number of events returned in this response.", + "type": "integer", + "format": "int64", + "example": 2 + }, + "next_stream_position": { + "description": "The stream position of the start of the next page (chunk)\nof events.", + "example": "1152922976252290886", + "anyOf": [ + { + "type": "string" + }, + { + "type": "number" + } + ] + }, + "entries": { + "description": "A list of events", + "type": "array", + "items": { + "$ref": "#/components/schemas/Event" + } + } + }, + "title": "Events", + "x-box-resource-id": "events", + "x-box-tag": "events" + }, + "File": { + "description": "A standard representation of a file, as returned from any\nfile API endpoints by default", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/File--Mini" + }, + { + "properties": { + "description": { + "description": "The optional description of this file.\nIf the description exceeds 255 characters, the first 255 characters\nare set as a file description and the rest of it is ignored.", + "type": "string", + "example": "Contract for Q1 renewal", + "maxLength": 255, + "nullable": false + }, + "size": { + "description": "The file size in bytes. Be careful parsing this integer as it can\nget very large and cause an integer overflow.", + "type": "integer", + "example": 629644, + "nullable": false + }, + "path_collection": { + "allOf": [ + { + "title": "Path collection", + "description": "A list of parent folders for an item.", + "type": "object", + "required": [ + "total_count", + "entries" + ], + "properties": { + "total_count": { + "description": "The number of folders in this list.", + "type": "integer", + "format": "int64", + "example": 1, + "nullable": false + }, + "entries": { + "description": "The parent folders for this item", + "type": "array", + "items": { + "$ref": "#/components/schemas/Folder--Mini" + }, + "nullable": false + } + } + }, + { + "description": "The tree of folders that this file is contained in,\nstarting at the root." + }, + { + "nullable": false + } + ] + }, + "created_at": { + "description": "The date and time when the file was created on Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": false + }, + "modified_at": { + "description": "The date and time when the file was last updated on Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": false + }, + "trashed_at": { + "description": "The time at which this file was put in the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "purged_at": { + "description": "The time at which this file is expected to be purged\nfrom the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "content_created_at": { + "description": "The date and time at which this file was originally\ncreated, which might be before it was uploaded to Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "content_modified_at": { + "description": "The date and time at which this file was last updated,\nwhich might be before it was uploaded to Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created this file" + } + ] + }, + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who last modified this file" + }, + { + "nullable": false + } + ] + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who owns this file" + }, + { + "nullable": false + } + ] + }, + "shared_link": { + "allOf": [ + { + "title": "Shared link", + "description": "Shared links provide direct, read-only access to files or folder on Box.\n\nShared links with open access level allow anyone with the URL\nto access the item, while shared links with company or collaborators access\nlevels can only be accessed by appropriately authenticated Box users.", + "type": "object", + "required": [ + "url", + "accessed", + "effective_access", + "effective_permission", + "is_password_enabled", + "download_count", + "preview_count" + ], + "properties": { + "url": { + "description": "The URL that can be used to access the item on Box.\n\nThis URL will display the item in Box's preview UI where the file\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.", + "type": "string", + "format": "url", + "example": "https://www.box.com/s/vspke7y05sb214wjokpk", + "nullable": false + }, + "download_url": { + "description": "A URL that can be used to download the file. This URL can be used in\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.", + "type": "string", + "format": "url", + "example": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg", + "nullable": true, + "x-box-premium-feature": true + }, + "vanity_url": { + "description": "The \"Custom URL\" that can also be used to preview the item on Box. Custom\nURLs can only be created or modified in the Box Web application.", + "type": "string", + "format": "url", + "example": "https://acme.app.box.com/v/my_url/", + "nullable": true + }, + "vanity_name": { + "description": "The custom name of a shared link, as used in the `vanity_url` field.", + "type": "string", + "example": "my_url", + "nullable": true + }, + "access": { + "description": "The access level for this shared link.\n\n* `open` - provides access to this item to anyone with this link\n* `company` - only provides access to this item to people the same company\n* `collaborators` - only provides access to this item to people who are\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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ], + "nullable": false + }, + "effective_access": { + "description": "The effective access level for the shared link. This can be a more\nrestrictive access level than the value in the `access` field when the\nenterprise settings restrict the allowed access levels.", + "type": "string", + "example": "company", + "enum": [ + "open", + "company", + "collaborators" + ], + "nullable": false + }, + "effective_permission": { + "description": "The effective permissions for this shared link.\nThese result in the more restrictive combination of\nthe share link permissions and the item permissions set\nby the administrator, the owner, and any ancestor item\nsuch as a folder.", + "type": "string", + "example": "can_download", + "enum": [ + "can_edit", + "can_download", + "can_preview", + "no_access" + ], + "nullable": false + }, + "unshared_at": { + "description": "The date and time when this link will be unshared. This field can only be\nset by users with paid accounts.", + "type": "string", + "format": "date-time", + "example": "2018-04-13T13:53:23-07:00", + "nullable": true + }, + "is_password_enabled": { + "description": "Defines if the shared link requires a password to access the item.", + "type": "boolean", + "example": true, + "nullable": false + }, + "permissions": { + "description": "Defines if this link allows a user to preview, edit, and download an item.\nThese permissions refer to the shared link only and\ndo not supersede permissions applied to the item itself.", + "type": "object", + "properties": { + "can_download": { + "description": "Defines if the shared link allows for the item to be downloaded. For\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`.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_preview": { + "description": "Defines if the shared link allows for the item to be previewed.\n\nThis value is always `true`. For shared links on folders this also\napplies to any items in the folder.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_edit": { + "description": "Defines if the shared link allows for the item to be edited.\n\nThis value can only be `true` if `can_download` is also `true` and if\nthe item has a type of `file`.", + "type": "boolean", + "example": false, + "nullable": false + } + }, + "required": [ + "can_download", + "can_preview", + "can_edit" + ] + }, + "download_count": { + "description": "The number of times this item has been downloaded.", + "type": "integer", + "example": 3, + "nullable": false + }, + "preview_count": { + "description": "The number of times this item has been previewed.", + "type": "integer", + "example": 3, + "nullable": false + } + } + }, + { + "description": "The shared link for this file. This will be\n`null` if no shared link has been created for this\nfile." + }, + { + "nullable": true + } + ] + }, + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The folder that this file is located within." + } + ], + "nullable": true + }, + "item_status": { + "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", + "type": "string", + "example": "active", + "enum": [ + "active", + "trashed", + "deleted" + ], + "nullable": false + } + } + } + ], + "title": "File", + "x-box-resource-id": "file", + "x-box-variant": "standard" + }, + "File--Base": { + "description": "The bare basic representation of a file, the minimal\namount of fields returned when using the `fields` query\nparameter.", + "type": "object", + "properties": { + "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`.", + "type": "string", + "example": "12345", + "nullable": false + }, + "etag": { + "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": "string", + "example": "1", + "nullable": true + }, + "type": { + "description": "`file`", + "type": "string", + "example": "file", + "enum": [ + "file" + ], + "nullable": false + } + }, + "nullable": true, + "required": [ + "id", + "type" + ], + "title": "File (Base)", + "x-box-resource-id": "file--base", + "x-box-tag": "files", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard", + "full" + ] + }, + "File--Full": { + "description": "A full representation of a file, as can be returned from any\nfile API endpoints by default", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/File" + }, + { + "properties": { + "version_number": { + "description": "The version number of this file", + "type": "string", + "example": "1" + }, + "comment_count": { + "description": "The number of comments on this file", + "type": "integer", + "example": 10 + }, + "permissions": { + "allOf": [ + { + "type": "object", + "description": "The permissions that the authenticated user has for a file.", + "required": [ + "can_annotate", + "can_comment", + "can_preview", + "can_upload", + "can_view_annotations_all", + "can_view_annotations_self" + ], + "allOf": [ + { + "type": "object", + "description": "The permissions that the authenticated user has for an item.", + "required": [ + "can_delete", + "can_download", + "can_invite_collaborator", + "can_rename", + "can_set_share_access", + "can_share" + ], + "properties": { + "can_delete": { + "description": "Specifies if the current user can delete this item.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_download": { + "description": "Specifies if the current user can download this item.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_invite_collaborator": { + "description": "Specifies if the current user can invite new\nusers to collaborate on this item, and if the user can\nupdate the role of a user already collaborated on this\nitem.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_rename": { + "description": "Specifies if the user can rename this item.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_set_share_access": { + "description": "Specifies if the user can change the access level of an\nexisting shared link on this item.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_share": { + "description": "Specifies if the user can create a shared link for this item.", + "type": "boolean", + "example": true, + "nullable": false + } + } + }, + { + "properties": { + "can_annotate": { + "description": "Specifies if the user can place annotations on this file.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_comment": { + "description": "Specifies if the user can place comments on this file.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_preview": { + "description": "Specifies if the user can preview this file.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_upload": { + "description": "Specifies if the user can upload a new version of this file.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_view_annotations_all": { + "description": "Specifies if the user view all annotations placed on this file", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_view_annotations_self": { + "description": "Specifies if the user view annotations placed by themselves\non this file", + "type": "boolean", + "example": true, + "nullable": false + } + } + } + ] + }, + { + "description": "Describes the permissions that the current user has\nfor this file." + }, + { + "nullable": false + } + ] + }, + "tags": { + "allOf": [ + { + "type": "array", + "example": [ + "approved" + ], + "items": { + "type": "string" + }, + "minItems": 1, + "maxItems": 100, + "description": "The tags for this item. These tags are shown in\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." + }, + { + "nullable": false + } + ] + }, + "lock": { + "allOf": [ + { + "title": "Lock", + "type": "object", + "description": "The lock held on a file. A lock prevents a file from being moved,\nrenamed, or otherwise changed by anyone else than the user who created the\nlock.", + "properties": { + "id": { + "description": "The unique identifier for this lock", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`lock`", + "type": "string", + "example": "lock", + "enum": [ + "lock" + ] + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created the lock." + } + ] + }, + "created_at": { + "description": "The time this lock was created at.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "expired_at": { + "description": "The time this lock is to expire at, which might be in the past.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "is_download_prevented": { + "description": "Whether or not the file can be downloaded while locked.", + "type": "boolean", + "example": true + }, + "app_type": { + "description": "If the lock is managed by an application rather than a user, this\nfield identifies the type of the application that holds the lock.\nThis is an open enum and may be extended with additional values in\nthe future.", + "type": "string", + "example": "office_wopiplus", + "enum": [ + "gsuite", + "office_wopi", + "office_wopiplus", + "other" + ], + "nullable": true + } + } + }, + { + "description": "The lock held on this file. If there is no lock, this can either\nbe `null` or have a timestamp in the past." + } + ], + "nullable": true + }, + "extension": { + "description": "Indicates the (optional) file extension for this file. By default,\nthis is set to an empty string.", + "type": "string", + "example": "pdf" + }, + "is_package": { + "description": "Indicates if the file is a package. Packages are commonly used\nby Mac Applications and can include iWork files.", + "type": "boolean", + "example": true + }, + "expiring_embed_link": { + "allOf": [ + { + "title": "Expiring embed link", + "type": "object", + "description": "An expiring Box Embed Link.", + "allOf": [ + { + "type": "object", + "description": "The basics of an access token", + "properties": { + "access_token": { + "description": "The requested access token.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + }, + "expires_in": { + "description": "The time in seconds by which this token will expire.", + "type": "integer", + "format": "int64", + "example": 3600 + }, + "token_type": { + "description": "The type of access token returned.", + "type": "string", + "example": "bearer", + "enum": [ + "bearer" + ] + }, + "restricted_to": { + "description": "The permissions that this access token permits,\nproviding a list of resources (files, folders, etc)\nand the scopes permitted for each of those resources.", + "type": "array", + "items": { + "$ref": "#/components/schemas/FileOrFolderScope" + } + } + } + }, + { + "properties": { + "url": { + "description": "The actual expiring embed URL for this file, constructed\nfrom the file ID and access tokens specified in this object.", + "type": "string", + "format": "url", + "example": "https://cloud.app.box.com/preview/expiring_embed/..." + } + } + } + ] + }, + { + "description": "Requesting this field creates an expiring Box Embed URL for an\nembedded preview session in an `iframe`.\n\nThis URL will expire after 60 seconds and the session will\nexpire after 60 minutes.\n\nNot all file types are supported for these embed URLs. Box Embed\nis not optimized for mobile browsers and should not be used in web\nexperiences designed for mobile devices. Many UI elements, like\nthe **download** and **print** options might not show in mobile\nbrowsers." + } + ] + }, + "watermark_info": { + "allOf": [ + { + "type": "object", + "description": "Details about the watermark applied to this item", + "properties": { + "is_watermarked": { + "description": "Specifies if this item has a watermark applied.", + "type": "boolean", + "example": true, + "nullable": false + } + } + }, + { + "description": "Details about the watermark applied to this file" + } + ] + }, + "is_accessible_via_shared_link": { + "description": "Specifies if the file can be accessed\nvia the direct shared link or a shared link\nto a parent folder.", + "type": "boolean", + "example": true, + "enum": [ + true, + false + ] + }, + "allowed_invitee_roles": { + "description": "A list of the types of roles that user can be invited at\nwhen sharing this file.", + "type": "array", + "items": { + "type": "string", + "enum": [ + "editor", + "viewer", + "previewer", + "uploader", + "previewer uploader", + "viewer uploader", + "co-owner" + ] + }, + "example": [ + "editor" + ], + "nullable": false + }, + "is_externally_owned": { + "description": "Specifies if this file is owned by a user outside of the\nauthenticated enterprise.", + "type": "boolean", + "example": true, + "nullable": false + }, + "has_collaborations": { + "description": "Specifies if this file has any other collaborators.", + "type": "boolean", + "example": true, + "nullable": false + }, + "metadata": { + "allOf": [ + { + "title": "Item metadata instances", + "type": "object", + "description": "A list of metadata instances, nested within key-value pairs of their `scope`\nand `templateKey`.\n\nTo access the metadata for a file or folder, first use the\nmetadata endpoints to determine the metadata templates available to your\nenterprise.\n\nThen use the `GET /files/:id` or `GET /folder/:id`\nendpoint with the `fields` query parameter to get\nthe metadata by ID.\n\nTo request a metadata instance for a particular `scope` and `templateKey`\nuse the following format for the `fields` parameter:\n`metadata..`\n\nFor example, `?fields=metadata.enterprise_27335.marketingCollateral`.", + "example": { + "enterprise_27335": { + "marketingCollateral": { + "$canEdit": true, + "$id": "01234500-12f1-1234-aa12-b1d234cb567e", + "$parent": "folder_59449484661", + "$scope": "enterprise_27335", + "$template": "marketingCollateral", + "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0", + "$typeVersion": 2, + "$version": 1 + } + } + }, + "additionalProperties": { + "type": "object", + "description": "A list of metadata instances, nested within key-value pairs of their `scope`\nand `templateKey`.", + "example": { + "marketingCollateral": { + "$canEdit": true, + "$id": "01234500-12f1-1234-aa12-b1d234cb567e", + "$parent": "folder_59449484661", + "$scope": "enterprise_27335", + "$template": "marketingCollateral", + "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0", + "$typeVersion": 2, + "$version": 1 + } + }, + "additionalProperties": { + "$ref": "#/components/schemas/Metadata--Full" + } + } + }, + { + "description": "An object containing the metadata instances that have been\nattached to this file.\n\nEach metadata instance is uniquely identified by its `scope` and\n`templateKey`. There can only be one instance of any metadata\ntemplate attached to each file. Each metadata instance is nested\nwithin an object with the `templateKey` as the key, which again\nitself is nested in an object with the `scope` as the key." + } + ] + }, + "expires_at": { + "description": "When the file will automatically be deleted", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "representations": { + "allOf": [ + { + "title": "Representations", + "description": "A list of file representations", + "type": "object", + "properties": { + "entries": { + "description": "A list of files", + "type": "array", + "items": { + "type": "object", + "description": "A file representation", + "properties": { + "content": { + "description": "An object containing the URL that can be used to actually fetch\nthe representation.", + "properties": { + "url_template": { + "description": "The download URL that can be used to fetch the representation.\nMake sure to make an authenticated API call to this endpoint.\n\nThis URL is a template and will require the `{+asset_path}` to\nbe replaced by a path. In general, for unpaged representations\nit can be replaced by an empty string.\n\nFor paged representations, replace the `{+asset_path}` with the\npage to request plus the extension for the file, for example\n`1.pdf`.\n\nWhen requesting the download URL the following additional\nquery params can be passed along.\n\n* `set_content_disposition_type` - Sets the\n`Content-Disposition` header in the API response with the\nspecified disposition type of either `inline` or `attachment`.\nIf not supplied, the `Content-Disposition` header is not\nincluded in the response.\n\n* `set_content_disposition_filename` - Allows the application to\n define the representation's file name used in the\n `Content-Disposition` header. If not defined, the filename\n is derived from the source file name in Box combined with the\n extension of the representation.", + "type": "string", + "example": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567" + } + }, + "type": "object" + }, + "info": { + "description": "An object containing the URL that can be used to fetch more info\non this representation.", + "type": "object", + "properties": { + "url": { + "description": "The API URL that can be used to get more info on this file\nrepresentation. Make sure to make an authenticated API call\nto this endpoint.", + "type": "string", + "example": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048" + } + } + }, + "properties": { + "description": "An object containing the size and type of this presentation.", + "type": "object", + "properties": { + "dimensions": { + "type": "string", + "format": "x", + "example": "2048x2048", + "description": "The width by height size of this representation in pixels." + }, + "paged": { + "type": "boolean", + "example": true, + "description": "Indicates if the representation is build up out of multiple\npages." + }, + "thumb": { + "type": "boolean", + "example": true, + "description": "Indicates if the representation can be used as a thumbnail of\nthe file." + } + } + }, + "representation": { + "description": "Indicates the file type of the returned representation.", + "type": "string", + "example": "png" + }, + "status": { + "description": "An object containing the status of this representation.", + "type": "object", + "properties": { + "state": { + "description": "The status of the representation.\n\n* `success` defines the representation as ready to be viewed.\n* `viewable` defines a video to be ready for viewing.\n* `pending` defines the representation as to be generated. Retry\n this endpoint to re-check the status.\n* `none` defines that the representation will be created when\n requested. Request the URL defined in the `info` object to\n trigger this generation.", + "type": "string", + "example": "success", + "enum": [ + "success", + "viewable", + "pending", + "none" + ] + } + } + } + } + } + } + } + }, + { + "description": "A list of representations for a file that can be used to\ndisplay a placeholder of the file in your application. By default\nthis returns all representations and we recommend using the\n`x-rep-hints` header to further customize the desired\nrepresentations." + } + ] + }, + "classification": { + "allOf": [ + { + "type": "object", + "description": "The classification applied to an item", + "properties": { + "name": { + "description": "The name of the classification", + "type": "string", + "example": "Top Secret" + }, + "definition": { + "description": "An explanation of the meaning of this classification.", + "type": "string", + "example": "Content that should not be shared outside the company." + }, + "color": { + "description": "The color that is used to display the\nclassification label in a user-interface. Colors are defined by the admin\nor co-admin who created the classification in the Box web app.", + "type": "string", + "example": "#FF0000" + } + } + }, + { + "description": "Details about the classification applied to this file." + }, + { + "nullable": true + } + ] + }, + "uploader_display_name": { + "allOf": [ + { + "title": "Uploader display name", + "type": "string", + "example": "Ellis Wiggins", + "nullable": false, + "description": "The display name of the user that uploaded the file. In most cases this is the\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`." + } + ] + }, + "disposition_at": { + "description": "The retention expiration timestamp for the given file", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "shared_link_permission_options": { + "description": "A list of the types of roles that user can be invited at\nwhen sharing this file.", + "type": "array", + "items": { + "type": "string", + "enum": [ + "can_preview", + "can_download", + "can_edit" + ] + }, + "example": [ + "can_preview" + ], + "nullable": true + }, + "is_associated_with_app_item": { + "description": "This field will return true if the file or any ancestor of the file\nis associated with at least one app item. Note that this will return\ntrue even if the context user does not have access to the app item(s)\nassociated with the file.", + "type": "boolean", + "example": true, + "nullable": false + } + } + } + ], + "title": "File (Full)", + "x-box-resource-id": "file--full", + "x-box-variant": "full" + }, + "File--Mini": { + "description": "A mini representation of a file, used when\nnested under another resource.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/File--Base" + }, + { + "properties": { + "sequence_id": { + "allOf": [ + { + "type": "string", + "example": "3", + "nullable": true, + "description": "A numeric identifier that represents the most recent user event\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." + }, + { + "nullable": false + } + ] + }, + "name": { + "description": "The name of the file", + "type": "string", + "example": "Contract.pdf" + }, + "sha1": { + "description": "The SHA1 hash of the file. This can be used to compare the contents\nof a file on Box with a local file.", + "type": "string", + "format": "digest", + "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37", + "nullable": false + }, + "file_version": { + "allOf": [ + { + "$ref": "#/components/schemas/FileVersion--Mini" + }, + { + "description": "The information about the current version of the file." + } + ] + } + } + } + ], + "nullable": true, + "title": "File (Mini)", + "x-box-resource-id": "file--mini", + "x-box-variant": "mini" + }, + "FileConflict": { + "description": "A representation of a file that is used to show", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/File--Mini" + }, + { + "properties": { + "sha1": { + "description": "The SHA1 hash of the file.", + "type": "string", + "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37" + }, + "file_version": { + "$ref": "#/components/schemas/FileVersion--Mini" + } + } + } + ], + "title": "File (Conflict)", + "x-box-resource-id": "file_conflict", + "x-box-tag": null + }, + "FileOrFolderScope": { + "description": "A relation between a resource (file or folder) and the scopes for which the resource can be accessed", + "type": "object", + "properties": { + "scope": { + "description": "The scopes for the resource access", + "type": "string", + "example": "item_download", + "enum": [ + "annotation_edit", + "annotation_view_all", + "annotation_view_self", + "base_explorer", + "base_picker", + "base_preview", + "base_upload", + "item_delete", + "item_download", + "item_preview", + "item_rename", + "item_share", + "item_upload" + ] + }, + "object": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "$ref": "#/components/schemas/File--Mini" + } + ] + }, + { + "description": "The file or folder resource" + } + ] + } + }, + "title": "File or folder scope" + }, + "FileRequest": { + "description": "A standard representation of a file request, as returned\nfrom any file request API endpoints by default.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this file request.", + "type": "string", + "example": "42037322", + "readOnly": true + }, + "type": { + "description": "`file_request`", + "type": "string", + "example": "file_request", + "enum": [ + "file_request" + ], + "readOnly": true + }, + "title": { + "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.", + "type": "string", + "example": "Please upload documents" + }, + "description": { + "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.", + "type": "string", + "example": "Following documents are requested for your process", + "nullable": true + }, + "status": { + "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.", + "type": "string", + "example": "active", + "enum": [ + "active", + "inactive" + ] + }, + "is_email_required": { + "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.", + "type": "boolean", + "example": true + }, + "is_description_required": { + "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.", + "type": "boolean", + "example": true + }, + "expires_at": { + "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`.", + "type": "string", + "format": "date-time", + "example": "2020-09-28T10:53:43-08:00" + }, + "folder": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The folder that this file request is associated with.\n\nFiles submitted through the file request form will be\nuploaded to this folder." + } + ], + "nullable": false + }, + "url": { + "description": "The generated URL for this file request. This URL can be shared\nwith users to let them upload files to the associated folder.", + "type": "string", + "example": "/f/19e57f40ace247278a8e3d336678c64a", + "readOnly": true + }, + "etag": { + "description": "The HTTP `etag` of this file. This can be used in combination with\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.", + "type": "string", + "example": "1", + "nullable": true + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created this file request." + } + ] + }, + "created_at": { + "description": "The date and time when the file request was created.", + "type": "string", + "format": "date-time", + "example": "2020-09-28T10:53:43-08:00", + "nullable": false + }, + "updated_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who last modified this file request." + }, + { + "nullable": false + } + ] + }, + "updated_at": { + "description": "The date and time when the file request was last updated.", + "type": "string", + "format": "date-time", + "example": "2020-09-28T10:53:43-08:00", + "nullable": false + } + }, + "required": [ + "id", + "type", + "folder", + "created_at", + "updated_at" + ], + "title": "File Request", + "x-box-resource-id": "file_request", + "x-box-tag": "file_requests" + }, + "FileRequestCopyRequest": { + "description": "The request body to copy a file request.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/FileRequestUpdateRequest" + }, + { + "properties": { + "folder": { + "description": "The folder to associate the new file request to.", + "type": "object", + "properties": { + "type": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ] + }, + "id": { + "description": "The ID of the folder to associate the new\nfile request to.", + "type": "string", + "example": "42037322" + } + }, + "required": [ + "id" + ] + } + } + } + ], + "required": [ + "folder" + ], + "title": "File Request (Copy)" + }, + "FileRequestUpdateRequest": { + "description": "The request body to update a file request.", + "type": "object", + "properties": { + "title": { + "description": "An optional new title for the file request. This can be\nused to change the title of the file request.\n\nThis will default to the value on the existing file request.", + "type": "string", + "example": "Please upload required documents" + }, + "description": { + "description": "An optional new description for the file request. This can be\nused to change the description of the file request.\n\nThis will default to the value on the existing file request.", + "type": "string", + "example": "Please upload required documents" + }, + "status": { + "description": "An optional new status of the file request.\n\nWhen the status is set to `inactive`, the file request\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.", + "type": "string", + "example": "active", + "enum": [ + "active", + "inactive" + ] + }, + "is_email_required": { + "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.", + "type": "boolean", + "example": true + }, + "is_description_required": { + "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.", + "type": "boolean", + "example": true + }, + "expires_at": { + "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.", + "type": "string", + "format": "date-time", + "example": "2020-09-28T10:53:43-08:00" + } + }, + "title": "File Request (Update)" + }, + "FileVersion": { + "description": "A standard representation of a file version", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/FileVersion--Mini" + }, + { + "properties": { + "name": { + "description": "The name of the file version", + "type": "string", + "example": "tigers.jpeg" + }, + "size": { + "description": "Size of the file version in bytes", + "type": "integer", + "format": "int64", + "example": 629644 + }, + "created_at": { + "description": "When the file version object was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When the file version object was last updated", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who last updated the file version" + } + ] + }, + "trashed_at": { + "description": "When the file version object was trashed.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "trashed_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who trashed the file version" + } + ] + }, + "restored_at": { + "description": "When the file version was restored from the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "restored_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who restored the file version from the trash." + } + ] + }, + "purged_at": { + "description": "When the file version object will be permanently deleted.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "uploader_display_name": { + "allOf": [ + { + "title": "Uploader display name", + "type": "string", + "example": "Ellis Wiggins", + "nullable": false, + "description": "The display name of the user that uploaded the file. In most cases this is the\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`." + } + ] + } + } + } + ], + "title": "File version", + "x-box-resource-id": "file_version", + "x-box-variant": "standard" + }, + "FileVersion--Base": { + "description": "The bare basic representation of a file version, the minimal\namount of fields returned when using the `fields` query\nparameter.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier that represent a file version.", + "type": "string", + "example": "12345", + "nullable": false + }, + "type": { + "description": "`file_version`", + "type": "string", + "example": "file_version", + "enum": [ + "file_version" + ], + "nullable": false + } + }, + "required": [ + "id", + "type" + ], + "title": "File version (Base)", + "x-box-resource-id": "file_version--base", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard", + "full" + ] + }, + "FileVersion--Full": { + "description": "A full representation of a file version, as can be returned from any\nfile version API endpoints by default", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/FileVersion" + }, + { + "properties": { + "version_number": { + "description": "The version number of this file version", + "type": "string", + "example": "1" + } + } + } + ], + "title": "File version (Full)", + "x-box-resource-id": "file_version--full", + "x-box-variant": "full" + }, + "FileVersion--Mini": { + "description": "A mini representation of a file version, used when\nnested within another resource.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/FileVersion--Base" + }, + { + "properties": { + "sha1": { + "description": "The SHA1 hash of this version of the file.", + "type": "string", + "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc" + } + } + } + ], + "title": "File version (Mini)", + "x-box-resource-id": "file_version--mini", + "x-box-variant": "mini" + }, + "FileVersionLegalHold": { + "description": "File version legal hold is an entity representing all\nholds on a File Version.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this file version legal hold", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`file_version_legal_hold`", + "type": "string", + "example": "file_version_legal_hold", + "enum": [ + "file_version_legal_hold" + ] + }, + "file_version": { + "allOf": [ + { + "$ref": "#/components/schemas/FileVersion--Mini" + }, + { + "description": "The file version that is held" + } + ] + }, + "file": { + "allOf": [ + { + "$ref": "#/components/schemas/File--Mini" + }, + { + "description": "The file for the file version held.\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": "#/components/schemas/LegalHoldPolicyAssignment" + } + }, + "deleted_at": { + "description": "Time that this File-Version-Legal-Hold was\ndeleted.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + }, + "title": "File version legal hold", + "x-box-resource-id": "file_version_legal_hold", + "x-box-tag": "file_version_legal_holds" + }, + "FileVersionLegalHolds": { + "description": "A list of file versions with legal holds.", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of file version legal holds", + "type": "array", + "items": { + "$ref": "#/components/schemas/FileVersionLegalHold" + } + } + } + } + ], + "title": "File version legal holds", + "x-box-resource-id": "file_version_legal_holds", + "x-box-tag": "file_version_legal_holds" + }, + "FileVersionRetention": { + "description": "A retention policy blocks permanent deletion of content\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 in your application management console.\n\n**Note**:\nFile retention API is now **deprecated**. \nTo get information about files and file versions under retention,\nsee [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this file version retention.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`file_version_retention`", + "type": "string", + "example": "file_version_retention", + "enum": [ + "file_version_retention" + ] + }, + "file_version": { + "allOf": [ + { + "$ref": "#/components/schemas/FileVersion--Mini" + }, + { + "description": "The file version this file version retention was\napplied to" + } + ] + }, + "file": { + "allOf": [ + { + "$ref": "#/components/schemas/File--Mini" + }, + { + "description": "The file this file version retention was applied to" + } + ] + }, + "applied_at": { + "description": "When this file version retention object was\ncreated", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "disposition_at": { + "description": "When the retention expires on this file\nversion retention", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "winning_retention_policy": { + "allOf": [ + { + "$ref": "#/components/schemas/RetentionPolicy--Mini" + }, + { + "description": "The winning retention policy applied to this file\nversion retention. A file version can have multiple\nretention policies applied." + } + ] + } + }, + "title": "File version retention", + "x-box-resource-id": "file_version_retention", + "x-box-tag": "file_version_retentions" + }, + "FileVersionRetentions": { + "description": "A list of file version retentions.\n\n**Note**:\nFile retention API is now **deprecated**. \nTo get information about files and file versions under retention,\nsee [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints.", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of file version retentions", + "type": "array", + "items": { + "$ref": "#/components/schemas/FileVersionRetention" + } + } + } + } + ], + "title": "File version retentions", + "x-box-resource-id": "file_version_retentions", + "x-box-tag": "file_version_retentions" + }, + "FileVersions": { + "description": "A list of file versions", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes pagination", + "properties": { + "total_count": { + "description": "One greater than the offset of the last entry in the entire collection.\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", + "example": 5000 + }, + "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", + "example": 1000 + }, + "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", + "example": 2000 + }, + "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", + "example": "type" + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "ASC", + "enum": [ + "ASC", + "DESC" + ] + } + } + } + } + } + }, + { + "properties": { + "entries": { + "description": "A list of file versions", + "type": "array", + "items": { + "$ref": "#/components/schemas/FileVersion--Full" + } + } + } + } + ], + "title": "File versions", + "x-box-resource-id": "file_versions", + "x-box-tag": "file_versions" + }, + "FileVersionsOnHold": { + "description": "A list of files on hold for legal policy assignment", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of file versions on hold.", + "type": "array", + "items": { + "$ref": "#/components/schemas/FileVersion" + } + } + } + } + ], + "title": "File versions on hold", + "x-box-resource-id": "file_versions_on_hold", + "x-box-tag": "legal_hold_policy_assignments" + }, + "Files": { + "description": "A list of files", + "type": "object", + "properties": { + "total_count": { + "description": "The number of files.", + "type": "integer", + "format": "int64", + "example": 1 + }, + "entries": { + "description": "A list of files", + "type": "array", + "items": { + "$ref": "#/components/schemas/File--Full" + } + } + }, + "title": "Files", + "x-box-resource-id": "files", + "x-box-tag": "files" + }, + "FilesOnHold": { + "description": "A list of files on hold for legal policy assignment", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of files", + "type": "array", + "items": { + "$ref": "#/components/schemas/File--Mini" + } + } + } + } + ], + "title": "Files on hold", + "x-box-resource-id": "files_on_hold", + "x-box-tag": "legal_hold_policy_assignments" + }, + "FilesUnderRetention": { + "description": "A list of files under retention.", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of files", + "type": "array", + "items": { + "$ref": "#/components/schemas/File--Mini" + } + } + } + } + ], + "title": "Files under retention", + "x-box-resource-id": "files_under_retention", + "x-box-tag": "retention_policy_assignments" + }, + "Folder": { + "description": "A standard representation of a folder, as returned from any\nfolder API endpoints by default", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "properties": { + "created_at": { + "description": "The date and time when the folder was created. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "modified_at": { + "description": "The date and time when the folder was last updated. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "description": { + "allOf": [ + { + "type": "string", + "description": "The optional description of this folder", + "maxLength": 256, + "example": "Legal contracts for the new ACME deal", + "nullable": false + }, + { + "nullable": false + } + ] + }, + "size": { + "description": "The folder size in bytes.\n\nBe careful parsing this integer as its\nvalue can get very large.", + "type": "integer", + "format": "int64", + "example": 629644, + "nullable": false + }, + "path_collection": { + "allOf": [ + { + "title": "Path collection", + "description": "A list of parent folders for an item.", + "type": "object", + "required": [ + "total_count", + "entries" + ], + "properties": { + "total_count": { + "description": "The number of folders in this list.", + "type": "integer", + "format": "int64", + "example": 1, + "nullable": false + }, + "entries": { + "description": "The parent folders for this item", + "type": "array", + "items": { + "$ref": "#/components/schemas/Folder--Mini" + }, + "nullable": false + } + } + }, + { + "description": "The tree of folders that this folder is contained in,\nstarting at the root." + }, + { + "nullable": false + } + ] + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created this folder" + }, + { + "nullable": false + } + ] + }, + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who last modified this folder." + }, + { + "nullable": false + } + ] + }, + "trashed_at": { + "description": "The time at which this folder was put in the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "purged_at": { + "description": "The time at which this folder is expected to be purged\nfrom the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "content_created_at": { + "description": "The date and time at which this folder was originally\ncreated.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "content_modified_at": { + "description": "The date and time at which this folder was last updated.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who owns this folder." + }, + { + "nullable": false + } + ] + }, + "shared_link": { + "allOf": [ + { + "title": "Shared link", + "description": "Shared links provide direct, read-only access to files or folder on Box.\n\nShared links with open access level allow anyone with the URL\nto access the item, while shared links with company or collaborators access\nlevels can only be accessed by appropriately authenticated Box users.", + "type": "object", + "required": [ + "url", + "accessed", + "effective_access", + "effective_permission", + "is_password_enabled", + "download_count", + "preview_count" + ], + "properties": { + "url": { + "description": "The URL that can be used to access the item on Box.\n\nThis URL will display the item in Box's preview UI where the file\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.", + "type": "string", + "format": "url", + "example": "https://www.box.com/s/vspke7y05sb214wjokpk", + "nullable": false + }, + "download_url": { + "description": "A URL that can be used to download the file. This URL can be used in\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.", + "type": "string", + "format": "url", + "example": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg", + "nullable": true, + "x-box-premium-feature": true + }, + "vanity_url": { + "description": "The \"Custom URL\" that can also be used to preview the item on Box. Custom\nURLs can only be created or modified in the Box Web application.", + "type": "string", + "format": "url", + "example": "https://acme.app.box.com/v/my_url/", + "nullable": true + }, + "vanity_name": { + "description": "The custom name of a shared link, as used in the `vanity_url` field.", + "type": "string", + "example": "my_url", + "nullable": true + }, + "access": { + "description": "The access level for this shared link.\n\n* `open` - provides access to this item to anyone with this link\n* `company` - only provides access to this item to people the same company\n* `collaborators` - only provides access to this item to people who are\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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ], + "nullable": false + }, + "effective_access": { + "description": "The effective access level for the shared link. This can be a more\nrestrictive access level than the value in the `access` field when the\nenterprise settings restrict the allowed access levels.", + "type": "string", + "example": "company", + "enum": [ + "open", + "company", + "collaborators" + ], + "nullable": false + }, + "effective_permission": { + "description": "The effective permissions for this shared link.\nThese result in the more restrictive combination of\nthe share link permissions and the item permissions set\nby the administrator, the owner, and any ancestor item\nsuch as a folder.", + "type": "string", + "example": "can_download", + "enum": [ + "can_edit", + "can_download", + "can_preview", + "no_access" + ], + "nullable": false + }, + "unshared_at": { + "description": "The date and time when this link will be unshared. This field can only be\nset by users with paid accounts.", + "type": "string", + "format": "date-time", + "example": "2018-04-13T13:53:23-07:00", + "nullable": true + }, + "is_password_enabled": { + "description": "Defines if the shared link requires a password to access the item.", + "type": "boolean", + "example": true, + "nullable": false + }, + "permissions": { + "description": "Defines if this link allows a user to preview, edit, and download an item.\nThese permissions refer to the shared link only and\ndo not supersede permissions applied to the item itself.", + "type": "object", + "properties": { + "can_download": { + "description": "Defines if the shared link allows for the item to be downloaded. For\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`.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_preview": { + "description": "Defines if the shared link allows for the item to be previewed.\n\nThis value is always `true`. For shared links on folders this also\napplies to any items in the folder.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_edit": { + "description": "Defines if the shared link allows for the item to be edited.\n\nThis value can only be `true` if `can_download` is also `true` and if\nthe item has a type of `file`.", + "type": "boolean", + "example": false, + "nullable": false + } + }, + "required": [ + "can_download", + "can_preview", + "can_edit" + ] + }, + "download_count": { + "description": "The number of times this item has been downloaded.", + "type": "integer", + "example": 3, + "nullable": false + }, + "preview_count": { + "description": "The number of times this item has been previewed.", + "type": "integer", + "example": 3, + "nullable": false + } + } + }, + { + "description": "The shared link for this folder. This will be\n`null` if no shared link has been created for this\nfolder." + } + ], + "nullable": true + }, + "folder_upload_email": { + "description": "The `folder_upload_email` parameter is not `null` if one of the following options is **true**:\n\n * The **Allow uploads to this folder via email** and the **Only allow email uploads from collaborators in this folder** are [enabled for a folder in the Admin Console](https://support.box.com/hc/en-us/articles/360043697534-Upload-to-Box-Through-Email), and the user has at least **Upload** permissions granted.\n\n * The **Allow uploads to this folder via email** setting is enabled for a folder in the Admin Console, and the **Only allow email uploads from collaborators in this folder** setting is deactivated (unchecked).\n\nIf the conditions are not met, the parameter will have the following value: `folder_upload_email: null`", + "type": "object", + "nullable": true, + "properties": { + "access": { + "description": "When this parameter has been set, users can email files\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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "collaborators" + ], + "nullable": false + }, + "email": { + "description": "The optional upload email address for this folder.", + "type": "string", + "format": "email", + "example": "upload.Contracts.asd7asd@u.box.com", + "nullable": false + } + } + }, + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the\nroot folder or the trash folder." + } + ], + "nullable": true + }, + "item_status": { + "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", + "type": "string", + "example": "active", + "enum": [ + "active", + "trashed", + "deleted" + ], + "nullable": false + }, + "item_collection": { + "allOf": [ + { + "$ref": "#/components/schemas/Items" + }, + { + "description": "A page of the items that are in the folder.\n\nThis field can only be requested when querying a folder's\ninformation, not when querying a folder's items." + }, + { + "nullable": false + } + ] + } + } + } + ], + "title": "Folder", + "x-box-resource-id": "folder", + "x-box-variant": "standard" + }, + "Folder--Base": { + "description": "The bare basic representation of a folder, the minimal\namount of fields returned when using the `fields` query\nparameter.", + "type": "object", + "properties": { + "id": { + "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`.", + "type": "string", + "example": "12345", + "nullable": false + }, + "etag": { + "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": "string", + "example": "1", + "nullable": true + }, + "type": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ], + "nullable": false + } + }, + "required": [ + "id", + "type" + ], + "title": "Folder (Base)", + "x-box-resource-id": "folder--base", + "x-box-tag": "folders", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard", + "full" + ] + }, + "Folder--Full": { + "description": "A full representation of a folder, as can be returned from any\nfolder API endpoints by default", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Folder" + }, + { + "properties": { + "sync_state": { + "allOf": [ + { + "type": "string", + "example": "synced", + "nullable": false, + "description": "Specifies whether a folder should be synced to a\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" + ] + } + ] + }, + "has_collaborations": { + "description": "Specifies if this folder has any other collaborators.", + "type": "boolean", + "example": true, + "nullable": false + }, + "permissions": { + "allOf": [ + { + "type": "object", + "description": "The permissions that the authenticated user has for a folder.", + "required": [ + "can_upload" + ], + "allOf": [ + { + "type": "object", + "description": "The permissions that the authenticated user has for an item.", + "required": [ + "can_delete", + "can_download", + "can_invite_collaborator", + "can_rename", + "can_set_share_access", + "can_share" + ], + "properties": { + "can_delete": { + "description": "Specifies if the current user can delete this item.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_download": { + "description": "Specifies if the current user can download this item.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_invite_collaborator": { + "description": "Specifies if the current user can invite new\nusers to collaborate on this item, and if the user can\nupdate the role of a user already collaborated on this\nitem.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_rename": { + "description": "Specifies if the user can rename this item.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_set_share_access": { + "description": "Specifies if the user can change the access level of an\nexisting shared link on this item.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_share": { + "description": "Specifies if the user can create a shared link for this item.", + "type": "boolean", + "example": true, + "nullable": false + } + } + }, + { + "properties": { + "can_upload": { + "description": "Specifies if the user can upload into this folder.", + "type": "boolean", + "example": true, + "nullable": false + } + } + } + ] + }, + { + "description": "Describes the permissions that the current user has\nfor this folder" + }, + { + "nullable": false + } + ] + }, + "tags": { + "allOf": [ + { + "type": "array", + "example": [ + "approved" + ], + "items": { + "type": "string" + }, + "minItems": 1, + "maxItems": 100, + "description": "The tags for this item. These tags are shown in\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." + }, + { + "nullable": false + } + ] + }, + "can_non_owners_invite": { + "allOf": [ + { + "type": "boolean", + "example": true, + "description": "Specifies if users who are not the owner\nof the folder can invite new collaborators to the folder." + }, + { + "nullable": false + } + ] + }, + "is_externally_owned": { + "description": "Specifies if this folder is owned by a user outside of the\nauthenticated enterprise.", + "type": "boolean", + "example": true, + "nullable": false + }, + "metadata": { + "allOf": [ + { + "title": "Item metadata instances", + "type": "object", + "description": "A list of metadata instances, nested within key-value pairs of their `scope`\nand `templateKey`.\n\nTo access the metadata for a file or folder, first use the\nmetadata endpoints to determine the metadata templates available to your\nenterprise.\n\nThen use the `GET /files/:id` or `GET /folder/:id`\nendpoint with the `fields` query parameter to get\nthe metadata by ID.\n\nTo request a metadata instance for a particular `scope` and `templateKey`\nuse the following format for the `fields` parameter:\n`metadata..`\n\nFor example, `?fields=metadata.enterprise_27335.marketingCollateral`.", + "example": { + "enterprise_27335": { + "marketingCollateral": { + "$canEdit": true, + "$id": "01234500-12f1-1234-aa12-b1d234cb567e", + "$parent": "folder_59449484661", + "$scope": "enterprise_27335", + "$template": "marketingCollateral", + "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0", + "$typeVersion": 2, + "$version": 1 + } + } + }, + "additionalProperties": { + "type": "object", + "description": "A list of metadata instances, nested within key-value pairs of their `scope`\nand `templateKey`.", + "example": { + "marketingCollateral": { + "$canEdit": true, + "$id": "01234500-12f1-1234-aa12-b1d234cb567e", + "$parent": "folder_59449484661", + "$scope": "enterprise_27335", + "$template": "marketingCollateral", + "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0", + "$typeVersion": 2, + "$version": 1 + } + }, + "additionalProperties": { + "$ref": "#/components/schemas/Metadata--Full" + } + } + }, + { + "description": "An object containing the metadata instances that have been\nattached to this folder.\n\nEach metadata instance is uniquely identified by its `scope` and\n`templateKey`. There can only be one instance of any metadata\ntemplate attached to each folder. Each metadata instance is nested\nwithin an object with the `templateKey` as the key, which again\nitself is nested in an object with the `scope` as the key." + } + ] + }, + "is_collaboration_restricted_to_enterprise": { + "allOf": [ + { + "type": "boolean", + "example": true, + "description": "Specifies if new invites to this folder are restricted to users\nwithin the enterprise. This does not affect existing\ncollaborations." + }, + { + "nullable": false + } + ] + }, + "allowed_shared_link_access_levels": { + "description": "A list of access levels that are available\nfor this folder.\n\nFor some folders, like the root folder, this will always\nbe an empty list as sharing is not allowed at that level.", + "type": "array", + "items": { + "type": "string", + "enum": [ + "open", + "company", + "collaborators" + ] + }, + "example": [ + "open" + ], + "nullable": false + }, + "allowed_invitee_roles": { + "description": "A list of the types of roles that user can be invited at\nwhen sharing this folder.", + "type": "array", + "items": { + "type": "string", + "enum": [ + "editor", + "viewer", + "previewer", + "uploader", + "previewer uploader", + "viewer uploader", + "co-owner" + ] + }, + "example": [ + "editor" + ], + "nullable": false + }, + "watermark_info": { + "allOf": [ + { + "type": "object", + "description": "Details about the watermark applied to this item", + "properties": { + "is_watermarked": { + "description": "Specifies if this item has a watermark applied.", + "type": "boolean", + "example": true, + "nullable": false + } + } + }, + { + "description": "Details about the watermark applied to this folder" + }, + { + "nullable": false + } + ] + }, + "is_accessible_via_shared_link": { + "description": "Specifies if the folder can be accessed\nwith the direct shared link or a shared link\nto a parent folder.", + "type": "boolean", + "example": true, + "enum": [ + true, + false + ] + }, + "can_non_owners_view_collaborators": { + "description": "Specifies if collaborators who are not owners\nof this folder are restricted from viewing other\ncollaborations on this folder.\n\nIt also restricts non-owners from inviting new\ncollaborators.", + "type": "boolean", + "example": true + }, + "classification": { + "allOf": [ + { + "type": "object", + "description": "The classification applied to an item", + "properties": { + "name": { + "description": "The name of the classification", + "type": "string", + "example": "Top Secret" + }, + "definition": { + "description": "An explanation of the meaning of this classification.", + "type": "string", + "example": "Content that should not be shared outside the company." + }, + "color": { + "description": "The color that is used to display the\nclassification label in a user-interface. Colors are defined by the admin\nor co-admin who created the classification in the Box web app.", + "type": "string", + "example": "#FF0000" + } + } + }, + { + "description": "Details about the classification applied to this folder." + }, + { + "nullable": true + } + ] + }, + "is_associated_with_app_item": { + "description": "This field will return true if the folder or any ancestor of the\nfolder is associated with at least one app item. Note that this will\nreturn true even if the context user does not have access to the\napp item(s) associated with the folder.", + "type": "boolean", + "example": true, + "nullable": false + } + } + } + ], + "title": "Folder (Full)", + "x-box-resource-id": "folder--full", + "x-box-variant": "full" + }, + "Folder--Mini": { + "description": "A mini representation of a file version, used when\nnested under another resource.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Base" + }, + { + "properties": { + "sequence_id": { + "allOf": [ + { + "type": "string", + "example": "3", + "nullable": true, + "description": "A numeric identifier that represents the most recent user event\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." + }, + { + "nullable": false + } + ] + }, + "name": { + "description": "The name of the folder.", + "type": "string", + "example": "Contracts", + "nullable": false + } + } + } + ], + "title": "Folder (Mini)", + "x-box-resource-id": "folder--mini", + "x-box-variant": "mini" + }, + "FolderLock": { + "description": "Folder locks define access restrictions placed by folder owners\nto prevent specific folders from being moved or deleted.", + "type": "object", + "properties": { + "folder": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The folder that the lock applies to." + } + ] + }, + "id": { + "description": "The unique identifier for this folder lock.", + "type": "string", + "example": "12345678" + }, + "type": { + "description": "The object type, always `folder_lock`.", + "type": "string", + "example": "folder_lock" + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user or group that created the lock." + } + ] + }, + "created_at": { + "description": "When the folder lock object was created.", + "type": "string", + "format": "date-time", + "example": "2020-09-14T23:12:53Z" + }, + "locked_operations": { + "description": "The operations that have been locked. Currently the `move`\nand `delete` operations cannot be locked separately, and both need to be\nset to `true`.\n", + "type": "object", + "properties": { + "move": { + "description": "Whether moving the folder is restricted.", + "type": "boolean", + "example": true, + "nullable": false + }, + "delete": { + "description": "Whether deleting the folder is restricted.", + "example": true, + "nullable": false, + "type": "boolean" + } + }, + "required": [ + "move", + "delete" + ] + }, + "lock_type": { + "description": "The lock type, always `freeze`.", + "type": "string", + "example": "freeze" + } + }, + "title": "Folder Lock", + "x-box-resource-id": "folder_lock", + "x-box-tag": "folder_locks" + }, + "FolderLocks": { + "description": "A list of folder locks", + "type": "object", + "properties": { + "entries": { + "description": "A list of folder locks", + "type": "array", + "items": { + "$ref": "#/components/schemas/FolderLock" + } + }, + "limit": { + "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", + "type": "string", + "example": "1000" + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + } + }, + "title": "Folder Locks", + "x-box-resource-id": "folder_locks", + "x-box-tag": "folder_locks" + }, + "GenericSource": { + "description": "A generic event source type.", + "type": "object", + "additionalProperties": { + "allOf": [ + {}, + { + "description": "A definition of a generic\nevent source object. The set of\nparameters depends on the\nobject type. For example, a Box Shield\nevent source would have the following\nset of parameters:\n```yaml\n{\n\"barrier_id\": 123456,\n\"barrier_status\": \"ENABLED\",\n\"barrier_segments\": [\n {\n \"name\": \"8\",\n \"member_count\": 1\n },\n {\n \"name\": \"9\",\n \"member_count\": 1\n }\n ]\n} \n```\n" + } + ] + }, + "title": "Generic source", + "x-box-resource-id": "generic_source" + }, + "Group": { + "description": "A standard representation of a group, as returned from any\ngroup API endpoints by default", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Group--Mini" + }, + { + "properties": { + "created_at": { + "description": "When the group object was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When the group object was last modified", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + } + } + ], + "title": "Group", + "x-box-resource-id": "group", + "x-box-variant": "standard" + }, + "Group--Base": { + "description": "A base representation of a group.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this object", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`group`", + "type": "string", + "example": "group", + "enum": [ + "group" + ] + } + }, + "required": [ + "id", + "type" + ], + "title": "Group (Base)", + "x-box-resource-id": "group--base", + "x-box-tag": "groups", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard", + "full" + ] + }, + "Group--Full": { + "description": "Groups contain a set of users, and can be used in place of\nusers in some operations, such as collaborations.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Group" + }, + { + "properties": { + "provenance": { + "description": "Keeps track of which external source this group is\ncoming from (e.g. \"Active Directory\", \"Google Groups\",\n\"Facebook Groups\"). Setting this will\nalso prevent Box users from editing the group name\nand its members directly via the Box web application.\nThis is desirable for one-way syncing of groups.", + "type": "string", + "example": "Active Directory", + "maxLength": 255 + }, + "external_sync_identifier": { + "description": "An arbitrary identifier that can be used by\nexternal group sync tools to link this Box Group to\nan external group. Example values of this field\ncould be an Active Directory Object ID or a Google\nGroup ID. We recommend you use of this field in\norder to avoid issues when group names are updated in\neither Box or external systems.", + "type": "string", + "example": "AD:123456" + }, + "description": { + "description": "Human readable description of the group.", + "type": "string", + "example": "Support Group - as imported from Active Directory", + "maxLength": 255 + }, + "invitability_level": { + "description": "Specifies who can invite the group to collaborate\non items.\n\nWhen set to `admins_only` the enterprise admin, co-admins,\nand the group's admin can invite the group.\n\nWhen set to `admins_and_members` all the admins listed\nabove and group members can invite the group.\n\nWhen set to `all_managed_users` all managed users in the\nenterprise can invite the group.", + "type": "string", + "example": "admins_only", + "enum": [ + "admins_only", + "admins_and_members", + "all_managed_users" + ] + }, + "member_viewability_level": { + "description": "Specifies who can view the members of the group\n(Get Memberships for 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", + "type": "string", + "example": "admins_only", + "enum": [ + "admins_only", + "admins_and_members", + "all_managed_users" + ] + }, + "permissions": { + "allOf": [ + { + "type": "object", + "description": "The permissions that the authenticated user has for a group.", + "properties": { + "can_invite_as_collaborator": { + "description": "Specifies if the user can invite the group to collaborate on any items.", + "type": "boolean", + "example": true + } + } + }, + { + "description": "Describes the permissions that the current user has\nfor this group." + } + ] + } + } + } + ], + "title": "Group (Full)", + "x-box-resource-id": "group--full", + "x-box-variant": "full" + }, + "Group--Mini": { + "description": "Mini representation of a group, including id and name of\ngroup.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Group--Base" + }, + { + "properties": { + "name": { + "description": "The name of the group", + "type": "string", + "example": "Support" + }, + "group_type": { + "description": "The type of the group.", + "type": "string", + "example": "managed_group", + "enum": [ + "managed_group", + "all_users_group" + ] + } + } + } + ], + "title": "Group (Mini)", + "x-box-resource-id": "group--mini", + "x-box-variant": "mini" + }, + "GroupMembership": { + "description": "Membership is used to signify that a user is part of a\ngroup.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this group membership", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`group_membership`", + "type": "string", + "example": "group_membership", + "enum": [ + "group_membership" + ] + }, + "user": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user that the membership applies to" + } + ] + }, + "group": { + "allOf": [ + { + "$ref": "#/components/schemas/Group--Mini" + }, + { + "description": "The group that the membership applies to" + } + ] + }, + "role": { + "description": "The role of the user in the group.", + "type": "string", + "example": "member", + "enum": [ + "member", + "admin" + ] + }, + "created_at": { + "description": "The time this membership was created.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "The time this membership was last modified.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + }, + "title": "Group membership", + "x-box-resource-id": "group_membership", + "x-box-tag": "memberships" + }, + "GroupMemberships": { + "description": "A list of group memberships.", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes pagination", + "properties": { + "total_count": { + "description": "One greater than the offset of the last entry in the entire collection.\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", + "example": 5000 + }, + "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", + "example": 1000 + }, + "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", + "example": 2000 + }, + "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", + "example": "type" + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "ASC", + "enum": [ + "ASC", + "DESC" + ] + } + } + } + } + } + }, + { + "properties": { + "entries": { + "description": "A list of group memberships", + "type": "array", + "items": { + "$ref": "#/components/schemas/GroupMembership" + } + } + } + } + ], + "title": "Group memberships", + "x-box-resource-id": "group_memberships", + "x-box-tag": "memberships" + }, + "Groups": { + "description": "A list of groups.", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes pagination", + "properties": { + "total_count": { + "description": "One greater than the offset of the last entry in the entire collection.\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", + "example": 5000 + }, + "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", + "example": 1000 + }, + "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", + "example": 2000 + }, + "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", + "example": "type" + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "ASC", + "enum": [ + "ASC", + "DESC" + ] + } + } + } + } + } + }, + { + "properties": { + "entries": { + "description": "A list of groups", + "type": "array", + "items": { + "$ref": "#/components/schemas/Group--Full" + } + } + } + } + ], + "title": "Groups", + "x-box-resource-id": "groups", + "x-box-tag": "groups" + }, + "IntegrationMapping": { + "description": "A Slack specific representation of an integration\nmapping object.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/IntegrationMapping--Base" + }, + { + "properties": { + "integration_type": { + "description": "Identifies the Box partner app,\nwith which the mapping is associated.\nCurrently only supports Slack.\n(part of the composite key together with `id`)", + "type": "string", + "example": "slack", + "enum": [ + "slack" + ], + "nullable": false + }, + "is_manually_created": { + "description": "Identifies whether the mapping has\nbeen manually set\n(as opposed to being automatically created)", + "type": "boolean", + "example": true, + "nullable": false + }, + "options": { + "allOf": [ + { + "$ref": "#/components/schemas/IntegrationMappingSlackOptions" + } + ], + "nullable": false + }, + "created_by": { + "description": "An object representing the user who\ncreated the integration mapping", + "allOf": [ + { + "$ref": "#/components/schemas/UserIntegrationMappings" + } + ], + "nullable": false + }, + "modified_by": { + "description": "The user who\nlast modified the integration mapping", + "allOf": [ + { + "$ref": "#/components/schemas/UserIntegrationMappings" + } + ], + "nullable": false + }, + "partner_item": { + "description": "Mapped item object for Slack", + "example": { + "id": "C12378991223", + "type": "channel", + "slack_org_id": "E1234567" + }, + "nullable": false, + "oneOf": [ + { + "$ref": "#/components/schemas/IntegrationMappingPartnerItemSlack" + } + ] + } + } + }, + { + "type": "object", + "properties": { + "box_item": { + "description": "The Box folder, to which the object from the\npartner app domain (referenced in `partner_item_id`) is mapped", + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + } + ], + "nullable": false + }, + "created_at": { + "description": "When the integration mapping object was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": false + }, + "modified_at": { + "description": "When the integration mapping object was last modified", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": false + } + }, + "required": [ + "box_item" + ] + } + ], + "required": [ + "partner_item" + ], + "title": "Integration mapping Slack", + "x-box-resource-id": "integration_mapping_slack", + "x-box-tag": "integration_mappings", + "x-box-variant": "standard" + }, + "IntegrationMapping--Base": { + "description": "A base representation of an\nintegration mapping object.", + "type": "object", + "properties": { + "id": { + "description": "A unique identifier of a folder mapping\n(part of a composite key together\nwith `integration_type`)", + "type": "string", + "example": "12345", + "nullable": false + }, + "type": { + "description": "Mapping type", + "type": "string", + "example": "integration_mapping", + "enum": [ + "integration_mapping" + ], + "nullable": false + } + }, + "required": [ + "id", + "type" + ], + "title": "Integration mapping (Base)", + "x-box-resource-id": "integration_mapping--base", + "x-box-tag": "integration_mappings", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard", + "mini" + ] + }, + "IntegrationMappingBoxItemSlack": { + "description": "The schema for an integration mapping Box item object for type Slack", + "type": "object", + "properties": { + "type": { + "description": "Type of the mapped item referenced in `id`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ], + "nullable": false + }, + "id": { + "description": "ID of the mapped item (of type referenced in `type`)", + "type": "string", + "example": "1234567891", + "nullable": false + } + }, + "required": [ + "id", + "type" + ], + "title": "Integration mapping Box item schema for type Slack" + }, + "IntegrationMappingPartnerItemSlack": { + "description": "The schema for an integration mapping mapped item object for type Slack.\n\nDepending if Box for Slack is installed at the org or workspace level,\nprovide **either** `slack_org_id` **or** `slack_workspace_id`.\nDo not use both parameters at the same time.", + "type": "object", + "properties": { + "type": { + "description": "Type of the mapped item referenced in `id`", + "type": "string", + "example": "channel", + "enum": [ + "channel" + ], + "nullable": false + }, + "id": { + "description": "ID of the mapped item (of type referenced in `type`)", + "type": "string", + "example": "C12378991223", + "nullable": false + }, + "slack_workspace_id": { + "description": "ID of the Slack workspace with which the item is associated. Use this parameter if Box for Slack is installed at a workspace level. Do not use `slack_org_id` at the same time.", + "type": "string", + "example": "T12352314", + "nullable": true + }, + "slack_org_id": { + "description": "ID of the Slack org with which the item is associated. Use this parameter if Box for Slack is installed at the org level. Do not use `slack_workspace_id` at the same time.", + "type": "string", + "example": "E1234567", + "nullable": true + } + }, + "required": [ + "id", + "type" + ], + "title": "Integration mapping mapped item schema for type Slack" + }, + "IntegrationMappingSlackCreateRequest": { + "description": "A request to create a\nSlack Integration Mapping object", + "type": "object", + "allOf": [ + { + "properties": { + "partner_item": { + "allOf": [ + { + "$ref": "#/components/schemas/IntegrationMappingPartnerItemSlack" + } + ], + "nullable": false + } + } + }, + { + "type": "object", + "properties": { + "box_item": { + "allOf": [ + { + "$ref": "#/components/schemas/IntegrationMappingBoxItemSlack" + } + ], + "nullable": false + }, + "options": { + "allOf": [ + { + "$ref": "#/components/schemas/IntegrationMappingSlackOptions" + } + ], + "nullable": false + } + }, + "required": [ + "box_item" + ] + } + ], + "required": [ + "partner_item" + ], + "title": "Create Slack integration mapping request", + "x-box-resource-id": "integration_mapping_slack_create_request" + }, + "IntegrationMappingSlackOptions": { + "description": "The schema for an integration mapping options object for Slack type.", + "type": "object", + "properties": { + "is_access_management_disabled": { + "description": "Indicates whether or not channel member\naccess to the underlying box item\nshould be automatically managed.\nDepending on type of channel, access is managed\nthrough creating collaborations or shared links.", + "type": "boolean", + "example": true, + "nullable": false + } + }, + "title": "Integration mapping options for type Slack" + }, + "IntegrationMappings": { + "description": "A list of integration mapping\nobjects.", + "type": "object", + "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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of integration mappings", + "type": "array", + "items": { + "$ref": "#/components/schemas/IntegrationMapping" + } + } + } + } + ], + "title": "Integration mappings Slack", + "x-box-resource-id": "integration_mappings_slack", + "x-box-tag": "integration_mappings" + }, + "Invite": { + "description": "An invite for a user to an enterprise.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this invite", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`invite`", + "type": "string", + "example": "invite", + "enum": [ + "invite" + ] + }, + "invited_to": { + "description": "A representation of a Box enterprise", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this enterprise.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`enterprise`", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise" + ] + }, + "name": { + "description": "The name of the enterprise", + "type": "string", + "example": "Acme Inc." + } + }, + "title": "Enterprise" + }, + "actionable_by": { + "$ref": "#/components/schemas/User--Mini" + }, + "invited_by": { + "$ref": "#/components/schemas/User--Mini" + }, + "status": { + "description": "The status of the invite", + "type": "string", + "example": "pending" + }, + "created_at": { + "description": "When the invite was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When the invite was modified.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + }, + "required": [ + "id", + "type" + ], + "title": "Invite", + "x-box-resource-id": "invite", + "x-box-tag": "invites" + }, + "Items": { + "description": "A list of files, folders, and web links in\ntheir mini representation.", + "type": "object", + "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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "type": "object", + "description": "The part of an API response that describes pagination", + "properties": { + "total_count": { + "description": "One greater than the offset of the last entry in the entire collection.\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", + "example": 5000 + }, + "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", + "example": 1000 + }, + "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", + "example": 2000 + }, + "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", + "example": "type" + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "ASC", + "enum": [ + "ASC", + "DESC" + ] + } + } + } + } + } + }, + { + "properties": { + "entries": { + "description": "The items in this collection.", + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/File--Full" + }, + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "$ref": "#/components/schemas/WebLink" + } + ] + } + } + } + } + ], + "title": "Items", + "x-box-resource-id": "items", + "x-box-tag": "folders" + }, + "KeywordSkillCard": { + "description": "A skill card that contains a set of keywords", + "type": "object", + "properties": { + "created_at": { + "description": "The optional date and time this card was created at.", + "type": "string", + "format": "date-time", + "example": "2018-04-13T13:53:23-07:00" + }, + "type": { + "description": "`skill_card`", + "type": "string", + "example": "skill_card", + "enum": [ + "skill_card" + ] + }, + "skill_card_type": { + "description": "`keyword`", + "type": "string", + "example": "keyword", + "enum": [ + "keyword" + ] + }, + "skill_card_title": { + "description": "The title of the card.", + "type": "object", + "properties": { + "code": { + "description": "An optional identifier for the title.", + "type": "string", + "example": "labels" + }, + "message": { + "description": "The actual title to show in the UI.", + "type": "string", + "example": "Labels" + } + }, + "required": [ + "message" + ] + }, + "skill": { + "description": "The service that applied this metadata.", + "type": "object", + "properties": { + "type": { + "description": "`service`", + "type": "string", + "example": "service", + "enum": [ + "service" + ] + }, + "id": { + "description": "A custom identifier that represent the service that\napplied this metadata.", + "type": "string", + "example": "image-recognition-service" + } + }, + "required": [ + "type", + "id" + ] + }, + "invocation": { + "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", + "type": "object", + "properties": { + "type": { + "description": "`skill_invocation`", + "type": "string", + "example": "skill_invocation", + "enum": [ + "skill_invocation" + ] + }, + "id": { + "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.", + "type": "string", + "example": "image-recognition-service-123" + } + }, + "required": [ + "type", + "id" + ] + }, + "entries": { + "description": "An list of entries in the metadata card.", + "type": "array", + "items": { + "type": "object", + "description": "An entry in the `entries` attribute of a metadata card", + "properties": { + "text": { + "description": "The text of the keyword.", + "type": "string", + "example": "keyword1" + } + } + } + } + }, + "required": [ + "type", + "skill_card_type", + "skill", + "invocation", + "entries" + ], + "title": "Keyword Skill Card", + "x-box-resource-id": "keyword_skill_card", + "x-box-tag": "skills" + }, + "LegalHoldPolicies": { + "description": "A list of legal hold policies.", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of legal hold policies", + "type": "array", + "items": { + "$ref": "#/components/schemas/LegalHoldPolicy" + } + } + } + } + ], + "title": "Legal hold policies", + "x-box-resource-id": "legal_hold_policies", + "x-box-tag": "legal_hold_policies" + }, + "LegalHoldPolicy": { + "description": "Legal Hold Policy information describes the basic\ncharacteristics of the Policy, such as name, description,\nand filter dates.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/LegalHoldPolicy--Mini" + }, + { + "properties": { + "policy_name": { + "description": "Name of the legal hold policy.", + "type": "string", + "example": "Policy 4", + "maxLength": 254 + }, + "description": { + "description": "Description of the legal hold policy. Optional\nproperty with a 500 character limit.", + "type": "string", + "example": "Postman created policy", + "maxLength": 500 + }, + "status": { + "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", + "type": "string", + "example": "active", + "enum": [ + "active", + "applying", + "releasing", + "released" + ] + }, + "assignment_counts": { + "description": "Counts of assignments within this a legal hold policy by item type", + "type": "object", + "properties": { + "user": { + "description": "The number of users this policy is applied to", + "type": "integer", + "format": "int64", + "example": 1 + }, + "folder": { + "description": "The number of folders this policy is applied to", + "type": "integer", + "format": "int64", + "example": 2 + }, + "file": { + "description": "The number of files this policy is applied to", + "type": "integer", + "format": "int64", + "example": 3 + }, + "file_version": { + "description": "The number of file versions this policy is applied to", + "type": "integer", + "format": "int64", + "example": 4 + } + } + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created the legal hold policy object" + } + ] + }, + "created_at": { + "description": "When the legal hold policy object was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When the legal hold policy object was modified.\nDoes not update when assignments are added or removed.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "deleted_at": { + "description": "When the policy release request was sent. (Because\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.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "filter_started_at": { + "description": "User-specified, optional date filter applies to\nCustodian assignments only", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "filter_ended_at": { + "description": "User-specified, optional date filter applies to\nCustodian assignments only", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "release_notes": { + "description": "Optional notes about why the policy was created.", + "type": "string", + "example": "Example", + "maxLength": 500 + } + } + } + ], + "title": "Legal hold policy", + "x-box-resource-id": "legal_hold_policy", + "x-box-variant": "standard" + }, + "LegalHoldPolicy--Mini": { + "description": "A mini legal hold policy", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this legal hold policy", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`legal_hold_policy`", + "type": "string", + "example": "legal_hold_policy", + "enum": [ + "legal_hold_policy" + ] + } + }, + "required": [ + "id", + "type" + ], + "title": "Legal hold policy (Mini)", + "x-box-resource-id": "legal_hold_policy--mini", + "x-box-tag": "legal_hold_policies", + "x-box-variant": "mini", + "x-box-variants": [ + "mini", + "standard" + ] + }, + "LegalHoldPolicyAssignment": { + "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.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/LegalHoldPolicyAssignment--Base" + }, + { + "properties": { + "legal_hold_policy": { + "allOf": [ + { + "$ref": "#/components/schemas/LegalHoldPolicy--Mini" + }, + { + "description": "The policy that the legal hold policy assignment\nis part of" + } + ] + }, + "assigned_to": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/File" + }, + { + "$ref": "#/components/schemas/Folder" + }, + { + "$ref": "#/components/schemas/WebLink" + } + ] + }, + { + "description": "The item that the the legal hold policy\nis assigned to. Includes type and ID." + } + ] + }, + "assigned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created the legal hold policy\nassignment" + } + ] + }, + "assigned_at": { + "description": "When the legal hold policy assignment object was\ncreated", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "deleted_at": { + "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.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + } + } + ], + "title": "Legal hold policy assignment", + "x-box-resource-id": "legal_hold_policy_assignment", + "x-box-tag": "legal_hold_policy_assignments" + }, + "LegalHoldPolicyAssignment--Base": { + "description": "Legal Hold Assignments are used to assign Legal Hold\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.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this legal hold assignment", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`legal_hold_policy_assignment`", + "type": "string", + "example": "legal_hold_policy_assignment", + "enum": [ + "legal_hold_policy_assignment" + ] + } + }, + "title": "Legal hold policy assignment (Base)", + "x-box-resource-id": "legal_hold_policy_assignment--base", + "x-box-tag": "legal_hold_policy_assignments", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard" + ] + }, + "LegalHoldPolicyAssignments": { + "description": "A list of legal hold policies assignments.", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of legal hold\npolicy assignments", + "type": "array", + "items": { + "$ref": "#/components/schemas/LegalHoldPolicyAssignment" + } + } + } + } + ], + "title": "Legal hold policy assignments", + "x-box-resource-id": "legal_hold_policy_assignments", + "x-box-tag": "legal_hold_policy_assignments" + }, + "Metadata": { + "description": "An instance of a metadata template, which has been applied to a file or\nfolder.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Metadata--Base" + } + ], + "title": "Metadata instance", + "x-box-resource-id": "metadata", + "x-box-tag": "file_metadata", + "x-box-variant": "standard" + }, + "Metadata--Base": { + "description": "The base representation of a metadata instance.", + "type": "object", + "properties": { + "$parent": { + "description": "The identifier of the item that this metadata instance\nhas been attached to. This combines the `type` and the `id`\nof the parent in the form `{type}_{id}`.", + "type": "string", + "example": "folder_59449484661," + }, + "$template": { + "description": "The name of the template", + "type": "string", + "example": "marketingCollateral" + }, + "$scope": { + "description": "An ID for the scope in which this template\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.", + "type": "string", + "example": "enterprise_27335" + }, + "$version": { + "description": "The version of the metadata instance. This version starts at 0 and\nincreases every time a user-defined property is modified.", + "type": "integer", + "example": 1 + } + }, + "title": "Metadata instance (Base)", + "x-box-resource-id": "metadata--base", + "x-box-tag": "file_metadata", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard", + "full" + ] + }, + "Metadata--Full": { + "description": "An instance of a metadata template, which has been applied to a file or\nfolder.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Metadata" + }, + { + "properties": { + "$canEdit": { + "description": "Whether the user can edit this metadata instance.", + "type": "boolean", + "example": true + }, + "$id": { + "description": "A UUID to identify the metadata instance.", + "type": "string", + "format": "uuid", + "example": "01234500-12f1-1234-aa12-b1d234cb567e", + "maxLength": 36 + }, + "$type": { + "description": "A unique identifier for the \"type\" of this instance. This is an\ninternal system property and should not be used by a client\napplication.", + "type": "string", + "example": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0" + }, + "$typeVersion": { + "description": "The last-known version of the template of the object. This is an\ninternal system property and should not be used by a client\napplication.", + "type": "integer", + "example": 2 + } + } + }, + { + "additionalProperties": { + "allOf": [ + {}, + { + "example": "Aaron Levie" + }, + { + "description": "A value for each of the fields that are present\non the metadata template.\nFor the `global.properties` template this can be\na list of zero or more fields,\nas this template allows for any generic key-value pairs \nto be stored stored in the template." + } + ], + "x-box-example-key": "name" + } + } + ], + "title": "Metadata instance (Full)", + "x-box-resource-id": "metadata--full", + "x-box-variant": "full" + }, + "MetadataCascadePolicies": { + "description": "A list of metadata cascade policies.", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of metadata cascade policies", + "type": "array", + "items": { + "$ref": "#/components/schemas/MetadataCascadePolicy" + } + } + } + } + ], + "title": "Metadata cascade policies", + "x-box-resource-id": "metadata_cascade_policies", + "x-box-tag": "metadata_cascade_policies" + }, + "MetadataCascadePolicy": { + "description": "A metadata cascade policy automatically applies a metadata template instance\nto all the files and folders within the targeted folder.", + "type": "object", + "properties": { + "id": { + "description": "The ID of the metadata cascade policy object", + "type": "string", + "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" + }, + "type": { + "description": "`metadata_cascade_policy`", + "type": "string", + "example": "metadata_cascade_policy", + "enum": [ + "metadata_cascade_policy" + ] + }, + "owner_enterprise": { + "description": "The enterprise that owns this policy.", + "type": "object", + "properties": { + "type": { + "description": "`enterprise`", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise" + ] + }, + "id": { + "description": "The ID of the enterprise that owns the policy.", + "type": "string", + "example": "690678" + } + } + }, + "parent": { + "description": "Represent the folder the policy is applied to.", + "type": "object", + "properties": { + "type": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ] + }, + "id": { + "description": "The ID of the folder the policy is applied to.", + "type": "string", + "example": "1234567" + } + } + }, + "scope": { + "description": "The scope of the metadata cascade policy can either be `global` or\n`enterprise_*`. The `global` scope is used for policies that are\navailable to any Box enterprise. The `enterprise_*` scope represents\npolicies that have been created within a specific enterprise, where `*`\nwill be the ID of that enterprise.", + "type": "string", + "example": "enterprise_123456" + }, + "templateKey": { + "description": "The key of the template that is cascaded down to the folder's\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", + "type": "string", + "example": "productInfo" + } + }, + "required": [ + "id", + "type" + ], + "title": "Metadata cascade policy", + "x-box-resource-id": "metadata_cascade_policy", + "x-box-tag": "metadata_cascade_policies" + }, + "MetadataFieldFilterDateRange": { + "description": "Specifies which `date` field on the template to filter the search\nresults by, specifying a range of dates that can match.", + "type": "object", + "properties": { + "lt": { + "description": "Specifies the (inclusive) upper bound for the metadata field\nvalue. The value of a field must be lower than (`lt`) or\nequal to this value for the search query to match this\ntemplate.", + "type": "string", + "format": "date-time", + "example": "2017-08-01T00:00:00Z" + }, + "gt": { + "description": "Specifies the (inclusive) lower bound for the metadata field\nvalue. The value of a field must be greater than (`gt`) or\nequal to this value for the search query to match this\ntemplate.", + "type": "string", + "format": "date-time", + "example": "2016-08-01T00:00:00Z" + } + }, + "title": "Metadata field filter (date range)", + "x-box-resource-id": "metadata_field_filter_date_range" + }, + "MetadataFieldFilterFloatRange": { + "description": "Specifies which `float` field on the template to filter the search\nresults by, specifying a range of values that can match.", + "type": "object", + "properties": { + "lt": { + "description": "Specifies the (inclusive) upper bound for the metadata field\nvalue. The value of a field must be lower than (`lt`) or\nequal to this value for the search query to match this\ntemplate.", + "type": "number", + "example": 200000 + }, + "gt": { + "description": "Specifies the (inclusive) lower bound for the metadata field\nvalue. The value of a field must be greater than (`gt`) or\nequal to this value for the search query to match this\ntemplate.", + "type": "number", + "example": 100000 + } + }, + "title": "Metadata field filter (float range)", + "x-box-resource-id": "metadata_field_filter_float_range" + }, + "MetadataFilter": { + "description": "A metadata template used to filter the search results.", + "type": "object", + "properties": { + "scope": { + "description": "Specifies the scope of the template to filter search results by.\n\nThis will be `enterprise_{enterprise_id}` for templates defined\nfor use in this enterprise, and `global` for general templates\nthat are available to all enterprises using Box.", + "type": "string", + "example": "enterprise", + "enum": [ + "global", + "enterprise", + "enterprise_{enterprise_id}" + ] + }, + "templateKey": { + "description": "The key of the template used to filter search results.\n\nIn many cases the template key is automatically derived\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", + "type": "string", + "example": "contract" + }, + "filters": { + "description": "Specifies which fields on the template to filter the search\nresults by. When more than one field is specified, the query\nperforms a logical `AND` to ensure that the instance of the\ntemplate matches each of the fields specified.", + "type": "object", + "example": { + "category": "online" + }, + "additionalProperties": { + "allOf": [ + { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "title": "Metadata field filter (multi-select)", + "type": "array", + "items": { + "type": "string" + }, + "description": "Specifies the values to match for a `multiSelect` metadata\nfield. When performing a search, the query will essentially\nperform an `OR` operation to match any template where any of\nthe provided values match this field.", + "example": [ + "online", + "enterprise" + ] + }, + { + "$ref": "#/components/schemas/MetadataFieldFilterFloatRange" + }, + { + "$ref": "#/components/schemas/MetadataFieldFilterDateRange" + } + ] + }, + { + "example": "online" + }, + { + "x-box-example-key": "category" + } + ] + } + } + }, + "title": "Metadata filter", + "x-box-resource-id": "metadata_filter", + "x-box-tag": "search" + }, + "MetadataQuery": { + "description": "Create a search using SQL-like syntax to return items that match specific\nmetadata.", + "type": "object", + "properties": { + "from": { + "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.", + "type": "string", + "example": "enterprise_123456.someTemplate" + }, + "query": { + "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.", + "type": "string", + "example": "value >= :amount" + }, + "query_params": { + "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.", + "type": "object", + "example": { + "amount": "100" + }, + "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.", + "example": "100", + "x-box-example-key": "amount" + } + }, + "ancestor_folder_id": { + "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.", + "type": "string", + "example": "0" + }, + "order_by": { + "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.", + "type": "array", + "items": { + "type": "object", + "description": "An object representing one of the metadata template fields to sort the\nmetadata query results by.", + "properties": { + "field_key": { + "description": "The metadata template field to order by.\n\nThe `field_key` represents the `key` value of a field from the\nmetadata template being searched for.", + "type": "string", + "example": "amount" + }, + "direction": { + "description": "The direction to order by, either ascending or descending.\n\nThe `ordering` direction must be the same for each item in the\narray.", + "type": "string", + "example": "asc", + "enum": [ + "ASC", + "DESC", + "asc", + "desc" + ] + } + } + } + }, + "limit": { + "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.", + "type": "integer", + "example": 50, + "default": 100, + "maximum": 100, + "minimum": 0 + }, + "marker": { + "description": "Marker to use for requesting the next page.", + "type": "string", + "example": "AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff" + }, + "fields": { + "description": "By default, this endpoint returns only the most basic info about the items for\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.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "extension", + "created_at", + "item_status", + "metadata.enterprise_1234.contracts", + "metadata.enterprise_1234.regions.location" + ] + } + }, + "required": [ + "from", + "ancestor_folder_id" + ], + "title": "Metadata query search request" + }, + "MetadataQueryIndex": { + "description": "A metadata query index", + "type": "object", + "properties": { + "id": { + "description": "The ID of the metadata query index.", + "type": "string", + "example": "-9876" + }, + "type": { + "description": "Value is always `metadata_query_index`", + "type": "string", + "example": "metadata_query_index", + "nullable": false + }, + "status": { + "description": "The status of the metadata query index", + "type": "string", + "example": "active", + "enum": [ + "building", + "active", + "disabled" + ], + "nullable": false + }, + "fields": { + "description": "A list of template fields which make up the index.", + "type": "array", + "items": { + "type": "object", + "description": "The field which makes up the index.", + "allOf": [ + { + "properties": { + "key": { + "description": "The metadata template field key.", + "type": "string", + "example": "vendor name" + }, + "sort_direction": { + "description": "The sort direction of the field.", + "type": "string", + "example": "asc", + "enum": [ + "asc", + "desc" + ] + } + } + } + ] + } + } + }, + "required": [ + "type", + "status" + ], + "title": "Metadata query index", + "x-box-resource-id": "metadata_query_index", + "x-box-tag": "search" + }, + "MetadataQueryResults": { + "description": "A page of files and folders that matched the metadata query.", + "type": "object", + "properties": { + "entries": { + "description": "The mini representation of the files and folders that match the search\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", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/File--Full" + }, + { + "$ref": "#/components/schemas/Folder--Full" + } + ] + }, + "x-box-resource-variant": 1 + }, + "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", + "example": 100, + "default": 100 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "0!-M7487OpVfBTNBV-XsQjU50gQFlbFFu5nArMWD7Ck61GH_Qo40M1S2xN5zWZPBzEjaQS1SOjJiQoo5BsXEl1bCVLRZ2pTqo4SKp9tyqzWQK2L51KR_nC1EgF5I_TJSFw7uO2Bx4HweGETOjh5_2oPSWw5iMkM-OvGApeR0lGFO48FDKoyzJyLgz5aogxoKd8VE09CesOOnTnmZvrW0puylDc-hFjY5YLmWFBKox3SOWiSDwKFkmZGNHyjEzza1nSwbZg6CYsAdGsDwGJhuCeTNsFzP5Mo5qx9wMloS0lSPuf2CcBInbIJzl2CKlXF3FvqhANttpm2nzdBTQRSoJyJnjVBpf4Q_HjV2eb4KIZBBlLy067UCVdv2AAWQFd5E2i6s1YiGRTtgMEZntOSUYD4IYLMWWm5Ra7ke_SP32SL3GSjbBQYIyCVQ.." + } + }, + "title": "Metadata query search results", + "x-box-resource-id": "metadata_query_results", + "x-box-tag": "search" + }, + "MetadataTemplate": { + "description": "A template for metadata that can be applied to files and folders", + "type": "object", + "properties": { + "id": { + "description": "The ID of the metadata template.", + "type": "string", + "example": "58063d82-4128-7b43-bba9-92f706befcdf" + }, + "type": { + "description": "`metadata_template`", + "type": "string", + "example": "metadata_template", + "enum": [ + "metadata_template" + ], + "nullable": false + }, + "scope": { + "description": "The scope of the metadata template can either be `global` or\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.", + "type": "string", + "example": "enterprise_123456" + }, + "templateKey": { + "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.", + "type": "string", + "example": "productInfo", + "maxLength": 64, + "pattern": "^[a-zA-Z_][-a-zA-Z0-9_]*$" + }, + "displayName": { + "description": "The display name of the template. This can be seen in the Box web app\nand mobile apps.", + "type": "string", + "example": "Product Info", + "maxLength": 4096 + }, + "hidden": { + "description": "Defines if this template is visible in the Box web app UI, or if\nit is purely intended for usage through the API.", + "type": "boolean", + "example": true + }, + "fields": { + "description": "An ordered list of template fields which are part of the template. Each\nfield can be a regular text field, date field, number field, as well as a\nsingle or multi-select list.", + "type": "array", + "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 (Read)", + "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": { + "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.\n\n**Note**: The `integer` value is deprecated.\nIt is still present in the response,\nbut cannot be used in the POST request.", + "type": "string", + "example": "string", + "enum": [ + "string", + "float", + "date", + "enum", + "multiSelect", + "integer" + ] + }, + "key": { + "description": "A unique identifier for the field. The identifier must\nbe unique within the template to which it belongs.", + "type": "string", + "example": "category", + "maxLength": 256 + }, + "displayName": { + "description": "The display name of the field as it is shown to the user in the web and\nmobile apps.", + "type": "string", + "example": "Category", + "maxLength": 4096 + }, + "description": { + "description": "A description of the field. This is not shown to the user.", + "type": "string", + "example": "The category", + "maxLength": 4096 + }, + "hidden": { + "description": "Whether this field is hidden in the UI for the user and can only be set\nthrough the API instead.", + "type": "boolean", + "example": true + }, + "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", + "example": "Category 1" + } + } + } + } + } + }, + { + "properties": { + "id": { + "description": "The unique ID of the metadata template field.", + "type": "string", + "example": "822227e0-47a5-921b-88a8-494760b2e6d2" + }, + "options": { + "description": "A list of options for this field. This is used in combination\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", + "example": "Category 1" + } + } + }, + { + "properties": { + "id": { + "description": "The internal unique identifier of the the option.", + "type": "string", + "example": "45dc2849-a4a7-40a9-a751-4a699a589190" + } + } + } + ] + } + } + } + } + ] + } + }, + "copyInstanceOnItemCopy": { + "description": "Whether or not to include the metadata when a file or folder is copied.", + "type": "boolean", + "example": true + } + }, + "required": [ + "type", + "id" + ], + "title": "Metadata template", + "x-box-resource-id": "metadata_template", + "x-box-tag": "metadata_templates" + }, + "MetadataTemplates": { + "description": "A list of metadata templates", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of metadata templates", + "type": "array", + "items": { + "$ref": "#/components/schemas/MetadataTemplate" + } + } + } + } + ], + "title": "Metadata templates", + "x-box-resource-id": "metadata_templates", + "x-box-tag": "metadata_templates" + }, + "Metadatas": { + "description": "A list of metadata instances that have been applied to a file or folder.", + "type": "object", + "properties": { + "entries": { + "description": "A list of metadata instances, as applied to this file or folder.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Metadata" + } + }, + "limit": { + "description": "The limit that was used for this page of results.", + "type": "integer", + "example": 100 + } + }, + "title": "Metadata instances", + "x-box-resource-id": "metadatas", + "x-box-tag": "file_metadata" + }, + "OAuth2Error": { + "description": "An OAuth 2.0 error", + "type": "object", + "properties": { + "error": { + "description": "The type of the error returned.", + "type": "string", + "example": "invalid_client" + }, + "error_description": { + "description": "The type of the error returned.", + "type": "string", + "example": "The client credentials are not valid" + } + }, + "title": "OAuth 2.0 error", + "x-box-resource-id": "oauth2_error", + "x-box-tag": "authorization" + }, + "Outcome": { + "description": "An instance of an outcome.", + "type": "object", + "properties": { + "id": { + "description": "ID of a specific outcome", + "type": "string", + "example": "17363629" + }, + "collaborators": { + "allOf": [ + { + "$ref": "#/components/schemas/CollaboratorVariable" + }, + { + "description": "Lists collaborators\naffected by the workflow\nresult." + } + ] + }, + "completion_rule": { + "allOf": [ + { + "$ref": "#/components/schemas/CompletionRuleVariable" + }, + { + "description": "Determines\nif an action should be completed\nby all or any assignees." + } + ] + }, + "file_collaborator_role": { + "allOf": [ + { + "$ref": "#/components/schemas/RoleVariable" + }, + { + "description": "Determines if the\nworkflow outcome for\na file\naffects a specific\ncollaborator role." + } + ] + }, + "task_collaborators": { + "allOf": [ + { + "$ref": "#/components/schemas/CollaboratorVariable" + }, + { + "description": "Lists collaborators\naffected by the task workflow\nresult." + } + ] + }, + "role": { + "allOf": [ + { + "$ref": "#/components/schemas/RoleVariable" + }, + { + "description": "Determines if the\nworkflow outcome\naffects a specific\ncollaborator role." + } + ] + } + }, + "required": [ + "id" + ], + "title": "Outcome" + }, + "PostOAuth2Revoke": { + "description": "A request to revoke an OAuth 2.0 token", + "type": "object", + "properties": { + "client_id": { + "description": "The Client ID of the application requesting to revoke the\naccess token.", + "type": "string", + "example": "ly1nj6n11vionaie65emwzk575hnnmrk" + }, + "client_secret": { + "description": "The client secret of the application requesting to revoke\nan access token.", + "type": "string", + "example": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1" + }, + "token": { + "description": "The access token to revoke.", + "type": "string", + "format": "token", + "example": "n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW" + } + }, + "required": [ + "grant_type" + ], + "title": "Token revocation request" + }, + "PostOAuth2Token": { + "description": "A request for a new OAuth 2.0 token", + "type": "object", + "properties": { + "grant_type": { + "description": "The type of request being made, either using a client-side obtained\nauthorization code, a refresh token, a JWT assertion, client credentials\ngrant or another access token for the purpose of downscoping a token.", + "type": "string", + "format": "urn", + "example": "authorization_code", + "enum": [ + "authorization_code", + "refresh_token", + "client_credentials", + "urn:ietf:params:oauth:grant-type:jwt-bearer", + "urn:ietf:params:oauth:grant-type:token-exchange" + ] + }, + "client_id": { + "description": "The Client ID of the application requesting an access token.\n\nUsed in combination with `authorization_code`, `client_credentials`, or\n`urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`.", + "type": "string", + "example": "ly1nj6n11vionaie65emwzk575hnnmrk" + }, + "client_secret": { + "description": "The client secret of the application requesting an access token.\n\nUsed in combination with `authorization_code`, `client_credentials`, or\n`urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`.", + "type": "string", + "example": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1" + }, + "code": { + "description": "The client-side authorization code passed to your application by\nBox in the browser redirect after the user has successfully\ngranted your application permission to make API calls on their\nbehalf.\n\nUsed in combination with `authorization_code` as the `grant_type`.", + "type": "string", + "format": "token", + "example": "n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW" + }, + "refresh_token": { + "description": "A refresh token used to get a new access token with.\n\nUsed in combination with `refresh_token` as the `grant_type`.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + }, + "assertion": { + "description": "A JWT assertion for which to request a new access token.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:jwt-bearer`\nas the `grant_type`.", + "type": "string", + "format": "jwt", + "example": "xxxxx.yyyyy.zzzzz" + }, + "subject_token": { + "description": "The token to exchange for a downscoped token. This can be a regular\naccess token, a JWT assertion, or an app token.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:token-exchange`\nas the `grant_type`.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + }, + "subject_token_type": { + "description": "The type of `subject_token` passed in.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:token-exchange`\nas the `grant_type`.", + "type": "string", + "example": "urn:ietf:params:oauth:token-type:access_token", + "enum": [ + "urn:ietf:params:oauth:token-type:access_token" + ] + }, + "actor_token": { + "description": "The token used to create an annotator token.\nThis is a JWT assertion.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:token-exchange`\nas the `grant_type`.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + }, + "actor_token_type": { + "description": "The type of `actor_token` passed in.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:token-exchange`\nas the `grant_type`.", + "type": "string", + "format": "urn", + "example": "urn:ietf:params:oauth:token-type:id_token", + "enum": [ + "urn:ietf:params:oauth:token-type:id_token" + ] + }, + "scope": { + "description": "The space-delimited list of scopes that you want apply to the\nnew access token.\n\nThe `subject_token` will need to have all of these scopes or\nthe call will error with **401 Unauthorized**.", + "type": "string", + "format": "space_delimited_list", + "example": "item_upload item_preview base_explorer" + }, + "resource": { + "description": "Full URL for the file that the token should be generated for.", + "type": "string", + "format": "url", + "example": "https://api.box.com/2.0/files/123456" + }, + "box_subject_type": { + "description": "Used in combination with `client_credentials` as the `grant_type`.", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise", + "user" + ] + }, + "box_subject_id": { + "description": "Used in combination with `client_credentials` as the `grant_type`.\nValue is determined by `box_subject_type`. If `user` use user ID and if\n`enterprise` use enterprise ID.", + "type": "string", + "example": "123456789" + }, + "box_shared_link": { + "description": "Full URL of the shared link on the file or folder\nthat the token should be generated for.", + "type": "string", + "format": "url", + "example": "https://cloud.box.com/s/123456" + } + }, + "required": [ + "grant_type" + ], + "title": "Token request" + }, + "PostOAuth2Token--RefreshAccessToken": { + "description": "A request to refresh an Access Token. Use this API to refresh an expired\nAccess Token using a valid Refresh Token.", + "type": "object", + "properties": { + "grant_type": { + "description": "The type of request being made, in this case a refresh request.", + "type": "string", + "format": "urn", + "example": "refresh_token", + "enum": [ + "refresh_token" + ] + }, + "client_id": { + "description": "The client ID of the application requesting to refresh the token.", + "type": "string", + "example": "ly1nj6n11vionaie65emwzk575hnnmrk" + }, + "client_secret": { + "description": "The client secret of the application requesting to refresh the token.", + "type": "string", + "example": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1" + }, + "refresh_token": { + "description": "The refresh token to refresh.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + } + }, + "required": [ + "grant_type", + "client_id", + "client_secret", + "refresh_token" + ], + "title": "Refresh access token" + }, + "RealtimeServer": { + "description": "A real-time server that can be used for\nlong polling user events", + "type": "object", + "properties": { + "type": { + "description": "`realtime_server`", + "type": "string", + "example": "realtime_server" + }, + "url": { + "description": "The URL for the server.", + "type": "string", + "example": "http://2.realtime.services.box.net/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all" + }, + "ttl": { + "description": "The time in minutes for which this server is available", + "type": "string", + "example": "10" + }, + "max_retries": { + "description": "The maximum number of retries this server will\nallow before a new long poll should be started by\ngetting a [new list of server](#options-events).", + "type": "string", + "example": "10" + }, + "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", + "example": 610 + } + }, + "title": "Real-time server", + "x-box-resource-id": "realtime_server" + }, + "RealtimeServers": { + "description": "A list of real-time servers that can\nbe used for long-polling.", + "type": "object", + "properties": { + "chunk_size": { + "description": "The number of items in this response.", + "type": "integer", + "format": "int64", + "example": 1 + }, + "entries": { + "description": "A list of real-time servers", + "type": "array", + "items": { + "$ref": "#/components/schemas/RealtimeServer" + } + } + }, + "title": "Real-time servers", + "x-box-resource-id": "realtime_servers", + "x-box-tag": "events" + }, + "RecentItem": { + "description": "A recent item accessed by a user.", + "type": "object", + "properties": { + "type": { + "description": "`recent_item`", + "type": "string", + "example": "recent_item" + }, + "item": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/File--Full" + }, + { + "$ref": "#/components/schemas/Folder--Full" + }, + { + "$ref": "#/components/schemas/WebLink" + } + ] + }, + { + "description": "The item that was recently accessed." + } + ] + }, + "interaction_type": { + "description": "The most recent type of access the user performed on\nthe item.", + "type": "string", + "example": "item_preview", + "enum": [ + "item_preview", + "item_upload", + "item_comment", + "item_open", + "item_modify" + ] + }, + "interacted_at": { + "description": "The time of the most recent interaction.", + "type": "string", + "format": "date-time", + "example": "2018-04-13T13:53:23-07:00" + }, + "interaction_shared_link": { + "description": "If the item was accessed through a shared link it will appear here,\notherwise this will be null.", + "type": "string", + "example": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg" + } + }, + "title": "Recent item", + "x-box-resource-id": "recent_item", + "x-box-tag": "recent_items" + }, + "RecentItems": { + "description": "A list of recent items.", + "type": "object", + "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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of recent items", + "type": "array", + "items": { + "$ref": "#/components/schemas/RecentItem" + } + } + } + } + ], + "title": "Recent items", + "x-box-resource-id": "recent_items" + }, + "RetentionPolicies": { + "description": "A list of retention policies.", + "type": "object", + "allOf": [ + { + "properties": { + "entries": { + "description": "A list in which each entry represents a retention policy object.", + "type": "array", + "items": { + "$ref": "#/components/schemas/RetentionPolicy" + } + } + } + }, + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + } + } + } + ], + "title": "Retention policies", + "x-box-resource-id": "retention_policies", + "x-box-tag": "retention_policies" + }, + "RetentionPolicy": { + "description": "A retention policy blocks permanent deletion of content\nfor a specified amount of time. Admins can create retention\npolicies and then later assign them to specific folders, metadata\ntemplates, or 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.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/RetentionPolicy--Mini" + }, + { + "properties": { + "description": { + "description": "The additional text description of the retention policy.", + "type": "string", + "example": "Policy to retain all reports for at least one month" + }, + "policy_type": { + "description": "The type of the retention policy. A retention\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.", + "type": "string", + "example": "finite", + "enum": [ + "finite", + "indefinite" + ] + }, + "retention_type": { + "description": "Specifies the retention type:\n\n* `modifiable`: You can modify the retention policy. For example,\n you can add or remove folders, shorten or lengthen\n the policy duration, or delete the assignment.\n Use this type if your retention policy\n is not related to any regulatory purposes.\n\n* `non-modifiable`: You can modify the retention policy\n only in a limited way: add a folder, lengthen the duration,\n retire the policy, change the disposition action\n or notification settings. You cannot perform other actions,\n such as deleting the assignment or shortening the\n policy duration. Use this type to ensure\n compliance with regulatory retention policies.", + "type": "string", + "example": "non_modifiable", + "enum": [ + "modifiable", + "non_modifiable" + ] + }, + "status": { + "description": "The status of the retention policy. The status of\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.", + "type": "string", + "example": "active", + "enum": [ + "active", + "retired" + ] + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "A mini user object representing the user that\ncreated the retention policy." + } + ] + }, + "created_at": { + "description": "When the retention policy object was created.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When the retention policy object was last modified.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "can_owner_extend_retention": { + "description": "Determines if the owner of items under the policy\ncan extend the retention when the original\nretention duration is about to end.", + "type": "boolean", + "example": false + }, + "are_owners_notified": { + "description": "Determines if owners and co-owners of items\nunder the policy are notified when\nthe retention duration is about to end.", + "type": "boolean", + "example": false + }, + "custom_notification_recipients": { + "description": "A list of users notified when the retention policy duration is about to end.", + "type": "array", + "items": { + "$ref": "#/components/schemas/User--Mini" + } + }, + "assignment_counts": { + "description": "Counts the retention policy assignments for each item type.", + "type": "object", + "properties": { + "enterprise": { + "description": "The number of enterprise assignments this policy has. The maximum value is 1.", + "type": "integer", + "format": "int64", + "example": 1 + }, + "folder": { + "description": "The number of folder assignments this policy has.", + "type": "integer", + "format": "int64", + "example": 1 + }, + "metadata_template": { + "description": "The number of metadata template assignments this policy has.", + "type": "integer", + "format": "int64", + "example": 1 + } + } + } + } + } + ], + "title": "Retention policy", + "x-box-resource-id": "retention_policy", + "x-box-tag": "retention_policies", + "x-box-variant": "standard" + }, + "RetentionPolicy--Base": { + "description": "A base representation of a retention policy.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier that represents a retention policy.", + "type": "string", + "example": "12345", + "nullable": false + }, + "type": { + "description": "`retention_policy`", + "type": "string", + "example": "retention_policy", + "enum": [ + "retention_policy" + ], + "nullable": false + } + }, + "required": [ + "id", + "type" + ], + "title": "Retention policy (Base)", + "x-box-resource-id": "retention_policy--base", + "x-box-tag": "retention_policies", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard" + ] + }, + "RetentionPolicy--Mini": { + "description": "A mini representation of a retention policy, used when\nnested within another resource.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/RetentionPolicy--Base" + }, + { + "properties": { + "policy_name": { + "description": "The name given to the retention policy.", + "type": "string", + "example": "Some Policy Name" + }, + "retention_length": { + "description": "The length of the retention policy. This value\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`.", + "type": "string", + "format": "int32", + "example": "365", + "minimum": 1 + }, + "disposition_action": { + "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.", + "type": "string", + "example": "permanently_delete", + "enum": [ + "permanently_delete", + "remove_retention" + ] + } + } + } + ], + "title": "Retention policy (Mini)", + "x-box-resource-id": "retention_policy--mini", + "x-box-variant": "mini" + }, + "RetentionPolicyAssignment": { + "description": "A retention assignment represents a rule specifying\nthe files a retention policy retains.\nAssignments can retain files based on their folder or metadata,\nor hold all files in the enterprise.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for a retention policy assignment.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`retention_policy_assignment`", + "type": "string", + "example": "retention_policy_assignment", + "enum": [ + "retention_policy_assignment" + ] + }, + "retention_policy": { + "allOf": [ + { + "$ref": "#/components/schemas/RetentionPolicy--Mini" + }, + { + "description": "A mini representation of a retention policy object\nthat has been assigned to the content." + } + ] + }, + "assigned_to": { + "description": "The `type` and `id` of the content that is under\nretention. The `type` can either be `folder`\n`enterprise`, or `metadata_template`.", + "type": "object", + "properties": { + "id": { + "description": "The ID of the folder, enterprise, or metadata template\nthe policy is assigned to.\nSet to null or omit when type is set to enterprise.", + "type": "string", + "example": "a983f69f-e85f-4ph4-9f46-4afdf9c1af65", + "nullable": true + }, + "type": { + "description": "The type of resource the policy is assigned to.", + "type": "string", + "example": "metadata_template", + "enum": [ + "folder", + "enterprise", + "metadata_template" + ] + } + } + }, + "filter_fields": { + "description": "An array of field objects. Values are only returned if the `assigned_to`\ntype is `metadata_template`. Otherwise, the array is blank.", + "type": "array", + "items": { + "type": "object", + "nullable": true, + "properties": { + "field": { + "description": "The metadata attribute key id.", + "type": "string", + "example": "a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4", + "nullable": true + }, + "value": { + "description": "The metadata attribute field id. For value, only\nenum and multiselect types are supported.", + "type": "string", + "example": "0c27b756-0p87-4fe0-a43a-59fb661ccc4e", + "nullable": true + } + } + }, + "nullable": true + }, + "assigned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "A mini user object representing the user that\ncreated the retention policy assignment." + } + ] + }, + "assigned_at": { + "description": "When the retention policy assignment object was\ncreated.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "start_date_field": { + "description": "The date the retention policy assignment begins.\nIf the `assigned_to` type is `metadata_template`,\nthis field can be a date field's metadata attribute key id.", + "type": "string", + "example": "upload_date" + } + }, + "required": [ + "id", + "type" + ], + "title": "Retention policy assignment", + "x-box-resource-id": "retention_policy_assignment", + "x-box-tag": "retention_policy_assignments" + }, + "RetentionPolicyAssignment--Base": { + "description": "A base representation of a retention policy assignment.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier that represents a file version.", + "type": "string", + "example": "12345", + "nullable": false + }, + "type": { + "description": "`retention_policy_assignment`", + "type": "string", + "example": "retention_policy_assignment", + "enum": [ + "retention_policy_assignment" + ], + "nullable": false + } + }, + "required": [ + "id", + "type" + ], + "title": "Retention policy assignment (Base)", + "x-box-resource-id": "retention_policy_assignment--base", + "x-box-tag": "retention_policy_assignments", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard" + ] + }, + "RetentionPolicyAssignments": { + "description": "A list of retention policy assignments.", + "type": "object", + "allOf": [ + { + "properties": { + "entries": { + "description": "A list of retention policy assignments", + "type": "array", + "items": { + "$ref": "#/components/schemas/RetentionPolicyAssignment" + } + } + } + }, + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + } + } + } + ], + "title": "Retention policy assignments", + "x-box-resource-id": "retention_policy_assignments", + "x-box-tag": "retention_policy_assignments" + }, + "RoleVariable": { + "description": "Determines if the\nworkflow outcome\naffects a specific\ncollaborator role.", + "type": "object", + "properties": { + "type": { + "description": "Role object type.\n", + "type": "string", + "example": "variable", + "enum": [ + "variable" + ] + }, + "variable_type": { + "description": "The variable type used\nby the object.\n", + "type": "string", + "example": "collaborator_role", + "enum": [ + "collaborator_role" + ] + }, + "variable_value": { + "allOf": [ + { + "type": "string", + "description": "The level of access granted.", + "example": "editor", + "enum": [ + "editor", + "viewer", + "previewer", + "uploader", + "previewer uploader", + "viewer uploader", + "co-owner" + ] + }, + { + "description": "Variable values you can use\nfor the role parameter." + } + ] + } + }, + "required": [ + "type", + "variable_type", + "variable_value" + ], + "title": "Role variable" + }, + "SearchResultWithSharedLink": { + "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`.", + "type": "object", + "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`.", + "type": "string", + "format": "url", + "example": "https://www.box.com/s/vspke7y05sb214wjokpk" + }, + "item": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/File--Full" + }, + { + "$ref": "#/components/schemas/Folder--Full" + }, + { + "$ref": "#/components/schemas/WebLink" + } + ] + }, + { + "description": "The file, folder or web link that matched the\nsearch query." + } + ] + }, + "type": { + "description": "The result type. The value is always `search_result`.", + "type": "string", + "example": "search_result" + } + }, + "title": "Search Result (including Shared Link)", + "x-box-resource-id": "search_result_with_shared_link", + "x-box-tag": "search" + }, + "SearchResults": { + "description": "A list of files, folders and web links that matched the search query.", + "type": "object", + "allOf": [ + { + "type": "object", + "properties": { + "total_count": { + "description": "One greater than the offset of the last entry in the search results.\nThe total number of entries in the collection may be less than\n`total_count`.", + "type": "integer", + "format": "int64", + "example": 5000 + }, + "limit": { + "description": "The limit that was used for this search. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed.", + "type": "integer", + "format": "int64", + "example": 1000 + }, + "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", + "example": 2000 + } + } + }, + { + "properties": { + "type": { + "description": "Specifies the response as search result items without shared links", + "type": "string", + "example": "search_results_items", + "enum": [ + "search_results_items" + ], + "nullable": false + }, + "entries": { + "description": "The search results for the query provided.", + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/File--Full" + }, + { + "$ref": "#/components/schemas/Folder--Full" + }, + { + "$ref": "#/components/schemas/WebLink" + } + ] + } + } + } + } + ], + "required": [ + "type" + ], + "title": "Search Results", + "x-box-resource-id": "search_results", + "x-box-tag": "search" + }, + "SearchResultsWithSharedLinks": { + "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`.", + "type": "object", + "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", + "example": 5000 + }, + "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", + "example": 1000 + }, + "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", + "example": 2000 + } + } + }, + { + "properties": { + "type": { + "description": "Specifies the response as search result items with shared links", + "type": "string", + "example": "search_results_with_shared_links", + "enum": [ + "search_results_with_shared_links" + ], + "nullable": false + }, + "entries": { + "description": "The search results for the query provided, including the\nadditional information about any shared links through\nwhich the item has been shared with the user.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SearchResultWithSharedLink" + } + } + } + } + ], + "required": [ + "type" + ], + "title": "Search Results (including Shared Links)", + "x-box-resource-id": "search_results_with_shared_links", + "x-box-tag": "search" + }, + "SessionTerminationMessage": { + "description": "A message informing about the\ntermination job status", + "type": "object", + "properties": { + "message": { + "description": "The unique identifier for the termination job status", + "type": "string", + "example": "Request is successful, please check the admin\nevents for the status of the job" + } + }, + "title": "Session termination message", + "x-box-resource-id": "session_termination", + "x-box-tag": "session_termination" + }, + "ShieldInformationBarrier": { + "description": "A standard representation of a\nshield information barrier object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the shield information barrier", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type of the shield information barrier", + "type": "string", + "example": "shield_information_barrier", + "enum": [ + "shield_information_barrier" + ] + }, + "enterprise": { + "description": "The `type` and `id` of enterprise this barrier is under.", + "allOf": [ + { + "$ref": "#/components/schemas/Enterprise--Base" + } + ] + }, + "status": { + "description": "Status of the shield information barrier", + "type": "string", + "example": "draft", + "enum": [ + "draft", + "pending", + "disabled", + "enabled", + "invalid" + ] + }, + "created_at": { + "description": "ISO date time string when this\nshield information barrier object was created.", + "type": "string", + "format": "date-time", + "example": "2020-06-26T18:44:45.869Z" + }, + "created_by": { + "description": "The user who created this shield information barrier.", + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + } + ] + }, + "updated_at": { + "description": "ISO date time string when this shield information barrier was updated.", + "type": "string", + "format": "date-time", + "example": "2020-07-26T18:44:45.869Z" + }, + "updated_by": { + "description": "The user that updated this shield information barrier.", + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + } + ] + }, + "enabled_at": { + "description": "ISO date time string when this shield information barrier was enabled.", + "type": "string", + "format": "date-time", + "example": "2020-07-26T18:44:45.869Z" + }, + "enabled_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user that enabled this shield information barrier." + } + ] + } + }, + "title": "Shield information barrier", + "x-box-resource-id": "shield_information_barrier", + "x-box-tag": "shield_information_barriers", + "x-box-variant": "standard", + "x-box-variants": [ + "base", + "standard" + ] + }, + "ShieldInformationBarrier--Base": { + "description": "A base representation of a\nshield information barrier object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the shield information barrier", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type of the shield information barrier", + "type": "string", + "example": "shield_information_barrier", + "enum": [ + "shield_information_barrier" + ] + } + }, + "title": "Shield information barrier (Base)", + "x-box-resource-id": "shield_information_barrier--base", + "x-box-tag": "shield_information_barriers", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard" + ] + }, + "ShieldInformationBarrierReference": { + "description": "A shield information barrier reference for requests and responses", + "type": "object", + "properties": { + "shield_information_barrier": { + "$ref": "#/components/schemas/ShieldInformationBarrier--Base" + } + }, + "title": "Shield information barrier reference", + "x-box-resource-id": "shield_information_barrier_reference", + "x-box-tag": "shield_information_barrier_reports" + }, + "ShieldInformationBarrierReport": { + "description": "A standard representation\nof a shield information barrier report object", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/ShieldInformationBarrierReport--Base" + }, + { + "properties": { + "shield_information_barrier": { + "allOf": [ + { + "$ref": "#/components/schemas/ShieldInformationBarrierReference" + } + ] + }, + "status": { + "description": "Status of the shield information report", + "type": "string", + "example": "pending", + "enum": [ + "pending", + "error", + "done", + "cancelled" + ] + }, + "details": { + "allOf": [ + { + "$ref": "#/components/schemas/ShieldInformationBarrierReportDetails" + } + ] + }, + "created_at": { + "description": "ISO date time string when this\nshield information barrier report object was created.", + "type": "string", + "format": "date-time", + "example": "2020-06-26T18:44:45.869Z" + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user who created this shield information barrier report." + } + ] + }, + "updated_at": { + "description": "ISO date time string when this\nshield information barrier report was updated.", + "type": "string", + "format": "date-time", + "example": "2020-07-26T18:44:45.869Z" + } + } + } + ], + "title": "Shield information barrier report", + "x-box-resource-id": "shield_information_barrier_report", + "x-box-tag": "shield_information_barrier_reports", + "x-box-variant": "standard", + "x-box-variants": [ + "base", + "standard" + ] + }, + "ShieldInformationBarrierReport--Base": { + "description": "A base representation of a\nshield information barrier report object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the shield information barrier report", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type of the shield information barrier report", + "type": "string", + "example": "shield_information_barrier_report", + "enum": [ + "shield_information_barrier_report" + ] + } + }, + "title": "Shield information barrier report (Base)", + "x-box-resource-id": "shield_information_barrier_report--base", + "x-box-tag": "shield_information_barrier_reports", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard" + ] + }, + "ShieldInformationBarrierReportDetails": { + "description": "Indicates which folder the report\nfile is located and any errors when generating the report.", + "type": "object", + "properties": { + "details": { + "type": "object", + "properties": { + "folder_id": { + "description": "Folder ID for locating this report", + "type": "string", + "example": "124235" + } + } + } + }, + "title": "Shield information barrier report details", + "x-box-resource-id": "shield_information_barrier_report_details", + "x-box-tag": "shield_information_barrier_reports" + }, + "ShieldInformationBarrierReports": { + "description": "A list of shield barrier reports.", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of shield information\nbarrier reports.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ShieldInformationBarrierReport" + } + } + } + } + ], + "title": "List of Shield Information Barrier Reports", + "x-box-resource-id": "shield_information_barrier_reports", + "x-box-tag": "shield_information_barrier_reports" + }, + "ShieldInformationBarrierSegment": { + "description": "A shield information barrier segment object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the shield information barrier segment", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type of the shield information barrier segment", + "type": "string", + "example": "shield_information_barrier_segment", + "enum": [ + "shield_information_barrier_segment" + ] + }, + "shield_information_barrier": { + "$ref": "#/components/schemas/ShieldInformationBarrier--Base" + }, + "name": { + "description": "Name of the shield information barrier segment", + "type": "string", + "example": "Investment Banking" + }, + "description": { + "description": "Description of the shield information barrier segment", + "type": "string", + "example": "'Corporate division that engages in advisory_based financial\n transactions on behalf of individuals, corporations, and governments.'" + }, + "created_at": { + "description": "ISO date time string when this shield information\nbarrier object was created.", + "type": "string", + "format": "date-time", + "example": "2020-06-26T18:44:45.869Z" + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user who created this shield information barrier segment." + } + ] + }, + "updated_at": { + "description": "ISO date time string when this\nshield information barrier segment was updated.", + "type": "string", + "format": "date-time", + "example": "2020-07-26T18:44:45.869Z" + }, + "updated_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user that updated this shield information barrier segment." + } + ] + } + }, + "title": "Shield information barrier segment", + "x-box-resource-id": "shield_information_barrier_segment", + "x-box-tag": "shield_information_barrier_segments" + }, + "ShieldInformationBarrierSegmentMember": { + "description": "A standard representation of a\nshield information barrier segment member object", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember--Mini" + }, + { + "properties": { + "shield_information_barrier": { + "$ref": "#/components/schemas/ShieldInformationBarrier--Base" + }, + "shield_information_barrier_segment": { + "description": "The `type` and `id` of the requested\nshield information barrier segment.", + "type": "object", + "properties": { + "id": { + "description": "The ID reference of the requesting\nshield information barrier segment.", + "type": "string", + "example": "432554" + }, + "type": { + "description": "The type of the shield information barrier segment", + "type": "string", + "example": "shield_information_barrier_segment", + "enum": [ + "shield_information_barrier_segment" + ] + } + } + }, + "user": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The `type` and `id` of the requested shield information barrier segment member." + } + ] + }, + "created_at": { + "description": "ISO date time string when this shield\ninformation barrier object was created.", + "type": "string", + "format": "date-time", + "example": "2020-06-26T18:44:45.869Z" + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user who created this shield information barrier segment member." + } + ] + }, + "updated_at": { + "description": "ISO date time string when this\nshield information barrier segment Member was updated.", + "type": "string", + "format": "date-time", + "example": "2020-07-26T18:44:45.869Z" + }, + "updated_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user that updated this shield information barrier segment Member." + } + ] + } + } + } + ], + "title": "Shield information barrier segment member", + "x-box-resource-id": "shield_information_barrier_segment_member", + "x-box-tag": "shield_information_barrier_segment_members", + "x-box-variant": "standard", + "x-box-variants": [ + "base", + "mini", + "standard" + ] + }, + "ShieldInformationBarrierSegmentMember--Base": { + "description": "A base representation of a\nshield information barrier segment member object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the\nshield information barrier segment member", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type of the shield information barrier segment member", + "type": "string", + "example": "shield_information_barrier_segment_member", + "enum": [ + "shield_information_barrier_segment_member" + ] + } + }, + "title": "Shield information barrier segment member (Base)", + "x-box-resource-id": "shield_information_barrier_segment_member--base", + "x-box-tag": "shield_information_barrier_segment_members", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard" + ] + }, + "ShieldInformationBarrierSegmentMember--Mini": { + "description": "A mini representation of a\nshield information barrier segment member object", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember--Base" + }, + { + "properties": { + "user": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The `type` and `id` of the requested shield information barrier segment member." + } + ] + } + } + } + ], + "title": "Shield information barrier segment member (Mini)", + "x-box-resource-id": "shield_information_barrier_segment_member--mini", + "x-box-tag": "shield_information_barrier_segment_members", + "x-box-variant": "mini", + "x-box-variants": [ + "base", + "mini", + "standard" + ] + }, + "ShieldInformationBarrierSegmentMembers": { + "description": "List of Shield Information Barrier Member objects", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of shield information\nbarrier segment members", + "type": "array", + "items": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember" + } + } + } + } + ], + "title": "List of Shield Information Barrier Segment Members", + "x-box-resource-id": "shield_information_barrier_segment_members", + "x-box-tag": "shield_information_barrier_segment_members" + }, + "ShieldInformationBarrierSegmentRestriction": { + "description": "A standard representation of a\nsegment restriction of a shield information barrier\nobject", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction--Mini" + }, + { + "properties": { + "shield_information_barrier": { + "$ref": "#/components/schemas/ShieldInformationBarrier--Base" + }, + "created_at": { + "description": "ISO date time string when this\nshield information barrier\nSegment Restriction object was created.", + "type": "string", + "format": "date-time", + "example": "2020-06-26T18:44:45.869Z" + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user who created this shield information barrier segment Restriction." + } + ] + }, + "updated_at": { + "description": "ISO date time string when this\nshield information barrier segment\nRestriction was updated.", + "type": "string", + "format": "date-time", + "example": "2020-07-26T18:44:45.869Z" + }, + "updated_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user that updated this shield information barrier segment Restriction." + } + ] + } + } + } + ], + "required": [ + "shield_information_barrier_segment", + "restricted_segment" + ], + "title": "Shield information barrier segment restriction", + "x-box-resource-id": "shield_information_barrier_segment_restriction", + "x-box-tag": "shield_information_barrier_segment_restrictions", + "x-box-variant": "standard", + "x-box-variants": [ + "base", + "mini", + "standard" + ] + }, + "ShieldInformationBarrierSegmentRestriction--Base": { + "description": "A base representation of\na segment restriction object for\nthe shield information barrier", + "type": "object", + "properties": { + "type": { + "description": "Shield information barrier segment restriction", + "type": "string", + "example": "shield_information_barrier_segment_restriction", + "enum": [ + "shield_information_barrier_segment_restriction" + ] + }, + "id": { + "description": "The unique identifier for the\nshield information barrier segment restriction.", + "type": "string", + "example": "11446498" + } + }, + "required": [ + "shield_information_barrier_segment", + "restricted_segment" + ], + "title": "Shield information barrier segment restriction (Base)", + "x-box-resource-id": "shield_information_barrier_segment_restriction--base", + "x-box-tag": "shield_information_barrier_segment_restrictions", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard" + ] + }, + "ShieldInformationBarrierSegmentRestriction--Mini": { + "description": "A mini representation of\na segment restriction object for\nthe shield information barrier", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction--Base" + }, + { + "properties": { + "shield_information_barrier_segment": { + "description": "The `type` and `id` of the\nrequested shield information barrier segment.", + "type": "object", + "properties": { + "id": { + "description": "The ID reference of the\nrequesting shield information barrier segment.", + "type": "string", + "example": "1910967" + }, + "type": { + "description": "The type of the shield information barrier segment", + "type": "string", + "example": "shield_information_barrier_segment", + "enum": [ + "shield_information_barrier_segment" + ] + } + } + }, + "restricted_segment": { + "description": "The `type` and `id` of the\nrestricted shield information barrier segment.", + "type": "object", + "properties": { + "id": { + "description": "The ID reference of the\nrestricted shield information barrier segment.", + "type": "string", + "example": "1910967" + }, + "type": { + "description": "The type of the shield information segment", + "type": "string", + "example": "shield_information_barrier_segment", + "enum": [ + "shield_information_barrier_segment" + ] + } + } + } + } + } + ], + "required": [ + "shield_information_barrier_segment", + "restricted_segment" + ], + "title": "Shield information barrier segment restriction (Mini)", + "x-box-resource-id": "shield_information_barrier_segment_restriction--mini", + "x-box-tag": "shield_information_barrier_segment_restrictions", + "x-box-variant": "mini", + "x-box-variants": [ + "base", + "mini", + "standard" + ] + }, + "ShieldInformationBarrierSegmentRestrictions": { + "description": "List of shield information barrier segment restriction objects", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of shield information barrier\nsegment restriction objects", + "type": "array", + "items": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction" + } + } + } + } + ], + "title": "List of Shield Information Barrier Segment Restrictions", + "x-box-resource-id": "shield_information_barrier_segment_restrictions", + "x-box-tag": "shield_information_barrier_segment_restrictions" + }, + "ShieldInformationBarrierSegments": { + "description": "List of Shield Information Barrier Segment objects", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of shield information barrier\nsegments", + "type": "array", + "items": { + "$ref": "#/components/schemas/ShieldInformationBarrierSegment" + } + } + } + } + ], + "title": "List of Shield Information Barrier Segments", + "x-box-resource-id": "shield_information_barrier_segments", + "x-box-tag": "shield_information_barrier_segments" + }, + "ShieldInformationBarriers": { + "description": "List of Shield Information Barrier objects", + "type": "object", + "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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of shield information barrier objects", + "type": "array", + "items": { + "$ref": "#/components/schemas/ShieldInformationBarrier" + } + } + } + } + ], + "title": "List of Shield Information Barriers", + "x-box-resource-id": "shield_information_barriers", + "x-box-tag": "shield_information_barriers" + }, + "SignRequest": { + "description": "A Box Sign request object.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/SignRequest--Base" + }, + { + "properties": { + "type": { + "description": "object type", + "type": "string", + "example": "sign-request", + "enum": [ + "sign-request" + ] + }, + "source_files": { + "description": "List of files to create a signing document from. This is currently limited to ten files. Only the ID and type fields are required for each file.", + "type": "array", + "items": { + "$ref": "#/components/schemas/File--Base" + } + }, + "signers": { + "description": "Array of signers for the signature request.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SignRequestSigner" + } + }, + "signature_color": { + "description": "Force a specific color for the signature (blue, black, or red).", + "type": "string", + "example": "blue", + "nullable": true + }, + "id": { + "description": "Box Sign request ID.", + "type": "string", + "example": "12345" + }, + "prepare_url": { + "description": "This URL is returned if `is_document_preparation_needed` is\nset to `true` in the request. The parameter is used to prepare\nthe signature request\nusing the UI. The signature request is not\nsent until the preparation\nphase is complete.", + "type": "string", + "example": "https://prepareurl.com", + "nullable": true + }, + "signing_log": { + "allOf": [ + { + "$ref": "#/components/schemas/File--Mini" + }, + { + "description": "Reference to a file that holds a log of all signer activity for\nthe request." + } + ] + }, + "status": { + "description": "Describes the status of the signature request.", + "type": "string", + "example": "converting", + "enum": [ + "converting", + "created", + "sent", + "viewed", + "signed", + "cancelled", + "declined", + "error_converting", + "error_sending", + "expired", + "finalizing", + "error_finalizing" + ] + }, + "sign_files": { + "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.", + "type": "object", + "properties": { + "files": { + "type": "array", + "items": { + "$ref": "#/components/schemas/File--Mini" + } + }, + "is_ready_for_download": { + "description": "Indicates whether the `sign_files` documents are processing\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.", + "type": "boolean", + "example": true + } + } + }, + "auto_expire_at": { + "description": "Uses `days_valid` to calculate the date and time, in GMT, the sign request will expire if unsigned.", + "type": "string", + "format": "date-time", + "example": "2021-04-26T08:12:13.982Z", + "nullable": true + }, + "parent_folder": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The destination folder to place final, signed document and signing\nlog.\n\nWhen this value was not passed in when the signature request was \ncreated, then we will use a default folder which is either the parent\nfolder of the first source file in the payload if we have the permission\nto upload to that folder or a folder called \"My Sign Requests\"." + } + ], + "nullable": false + } + } + } + ], + "title": "Box Sign request", + "x-box-resource-id": "sign_request", + "x-box-tag": "sign_requests", + "x-box-variant": "standard", + "x-box-variants": [ + "standard", + "base" + ] + }, + "SignRequest--Base": { + "description": "A standard representation of a signature request object.", + "type": "object", + "properties": { + "is_document_preparation_needed": { + "description": "Indicates if the sender should receive a `prepare_url` in the response to complete document preparation using the UI.", + "type": "boolean", + "example": true + }, + "redirect_url": { + "description": "When specified, the signature request will be redirected to this url when a document is signed.", + "type": "string", + "example": "https://www.example.com", + "nullable": true + }, + "declined_redirect_url": { + "description": "The uri that a signer will be redirected to after declining to sign a document.", + "type": "string", + "example": "https://declined-redirect.com", + "nullable": true + }, + "are_text_signatures_enabled": { + "description": "Disables the usage of signatures generated by typing (text).", + "type": "boolean", + "example": true, + "default": true + }, + "email_subject": { + "description": "Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.", + "type": "string", + "example": "Sign Request from Acme", + "nullable": true + }, + "email_message": { + "description": "Message to include in sign request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used.", + "type": "string", + "example": "Hello! Please sign the document below", + "nullable": true + }, + "are_reminders_enabled": { + "description": "Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers.", + "type": "boolean", + "example": true + }, + "name": { + "description": "Name of the signature request.", + "type": "string", + "example": "name" + }, + "prefill_tags": { + "description": "When a document contains sign-related tags in the content, you can prefill them using this `prefill_tags` by referencing the 'id' of the tag as the `external_id` field of the prefill tag.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SignRequestPrefillTag" + } + }, + "days_valid": { + "description": "Set the number of days after which the created signature request will automatically expire if not completed. By default, we do not apply any expiration date on signature requests, and the signature request does not expire.", + "type": "integer", + "example": 2, + "maximum": 730, + "minimum": 0, + "nullable": true + }, + "external_id": { + "description": "This can be used to reference an ID in an external system that the sign request is related to.", + "type": "string", + "example": "123", + "nullable": true + }, + "is_phone_verification_required_to_view": { + "description": "Forces signers to verify a text message prior to viewing the document. You must specify the phone number of signers to have this setting apply to them.", + "type": "boolean", + "example": true, + "nullable": true + }, + "template_id": { + "description": "When a signature request is created from a template this field will indicate the id of that template.", + "type": "string", + "example": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb", + "nullable": true + }, + "external_system_name": { + "description": "Used as an optional system name to appear in the signature log next to the signers who have been assigned the `embed_url_external_id`.", + "type": "string", + "example": "Box", + "nullable": true + } + }, + "title": "Box Sign request (Base)", + "x-box-resource-id": "sign_request--base", + "x-box-tag": "sign_requests", + "x-box-variant": "base", + "x-box-variants": [ + "standard", + "base" + ] + }, + "SignRequestCreateRequest": { + "description": "Creates a Box Sign request object.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/SignRequest--Base" + }, + { + "properties": { + "source_files": { + "description": "List of files to create a signing document from. This is currently limited to ten files. Only the ID and type fields are required for each file.", + "type": "array", + "items": { + "$ref": "#/components/schemas/File--Base" + }, + "maxItems": 10, + "nullable": true + }, + "signature_color": { + "description": "Force a specific color for the signature (blue, black, or red)", + "type": "string", + "example": "blue", + "enum": [ + "blue", + "black", + "red" + ], + "nullable": true + }, + "signers": { + "description": "Array of signers for the signature request. 35 is the\nmax number of signers permitted.\n\n**Note**: It may happen that some signers belong to conflicting [segments](r://shield-information-barrier-segment-member) (user groups).\nThis means that due to the security policies, users are assigned to segments to prevent exchanges or communication that could lead to ethical conflicts.\nIn such a case, an attempt to send the sign request will result in an error.\n\nRead more about [segments and ethical walls](https://support.box.com/hc/en-us/articles/9920431507603-Understanding-Information-Barriers#h_01GFVJEHQA06N7XEZ4GCZ9GFAQ).", + "type": "array", + "items": { + "$ref": "#/components/schemas/SignRequestCreateSigner" + } + }, + "parent_folder": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The destination folder to place final, signed document and signing\nlog. Only `ID` and `type` fields are required. The root folder,\nfolder ID `0`, cannot be used and can also not be null.\n\nWhen this value is not passed in when the signature request, then\nwe will use a default folder which is either the parent folder of\nthe first source file in the payload if we have the permission to\nupload to that folder or a folder called \"My Sign Requests\"." + } + ] + } + } + } + ], + "required": [ + "signers" + ], + "title": "Create a Box Sign request" + }, + "SignRequestCreateSigner": { + "description": "The schema for a Signer object used in\nfor creating a Box Sign request object.", + "type": "object", + "properties": { + "email": { + "description": "Email address of the signer.\nThe email address of the signer is required when making signature requests, except when using templates that are configured to include emails.", + "type": "string", + "example": "example@gmail.com", + "nullable": true + }, + "role": { + "description": "Defines the role of the signer in the signature request. A `signer`\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.", + "type": "string", + "example": "signer", + "default": "signer", + "enum": [ + "signer", + "approver", + "final_copy_reader" + ] + }, + "is_in_person": { + "description": "Used in combination with an embed URL for a sender. After the\nsender signs, they are redirected to the next `in_person` signer.", + "type": "boolean", + "example": true + }, + "order": { + "description": "Order of the signer", + "type": "integer", + "example": 2, + "minimum": 0 + }, + "embed_url_external_user_id": { + "description": "User ID for the signer in an external application responsible\nfor authentication when accessing the embed URL.", + "type": "string", + "example": "1234", + "nullable": true + }, + "redirect_url": { + "description": "The URL that a signer will be redirected\nto after signing a document. Defining this URL\noverrides default or global redirect URL\nsettings for a specific signer.\nIf no declined redirect URL is specified,\nthis URL will be used for decline actions as well.", + "type": "string", + "example": "https://example.com", + "nullable": true + }, + "declined_redirect_url": { + "description": "The URL that a signer will be redirect\nto after declining to sign a document.\nDefining this URL overrides default or global\ndeclined redirect URL settings for a specific signer.", + "type": "string", + "example": "https://declined-example.com", + "nullable": true + }, + "login_required": { + "description": "If set to true, the signer will need to log in to a Box account\nbefore signing the request. If the signer does not have\nan existing account, they will have the option to create\na free Box account. Cannot be selected in combination with\n`verification_phone_number`.", + "type": "boolean", + "example": true, + "nullable": true + }, + "verification_phone_number": { + "description": "If set, this phone number will be used to verify the signer\nvia two-factor authentication before they are able to sign the document.\nCannot be selected in combination with `login_required`.", + "type": "string", + "example": "6314578901", + "nullable": true + }, + "password": { + "description": "If set, the signer is required to enter the password before they are able\nto sign a document. This field is write only.", + "type": "string", + "example": "SecretPassword123", + "nullable": true, + "writeOnly": true + }, + "signer_group_id": { + "description": "If set, signers who have the same value will be assigned to the same input and to the same signer group.\nA signer group is not a Box Group. It is an entity that belongs to a Sign Request and can only be\nused/accessed within this Sign Request. A signer group is expected to have more than one signer.\nIf the provided value is only used for one signer, this value will be ignored and request will be handled\nas it was intended for an individual signer. The value provided can be any string and only used to\ndetermine which signers belongs to same group. A successful response will provide a generated UUID value\ninstead for signers in the same signer group.", + "type": "string", + "example": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7", + "nullable": true + }, + "suppress_notifications": { + "description": "If true, no emails about the sign request will be sent", + "type": "boolean", + "example": false, + "nullable": true + } + }, + "title": "Signer fields used to create a Box Sign request object." + }, + "SignRequestPrefillTag": { + "description": "Prefill tags are used to prefill placeholders with signer input data. Only\none value field can be included.", + "type": "object", + "properties": { + "document_tag_id": { + "description": "This references the ID of a specific tag contained in a file of the signature request.", + "type": "string", + "example": "1234", + "nullable": true + }, + "text_value": { + "description": "Text prefill value", + "type": "string", + "example": "text", + "nullable": true + }, + "checkbox_value": { + "description": "Checkbox prefill value", + "type": "boolean", + "example": true, + "nullable": true + }, + "date_value": { + "description": "Date prefill value", + "type": "string", + "format": "date", + "example": "2021-04-26", + "nullable": true + } + }, + "title": "Sign request prefill tag" + }, + "SignRequestSigner": { + "description": "The schema for a Signer object used\non the body of a Box Sign request object.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/SignRequestCreateSigner" + }, + { + "properties": { + "has_viewed_document": { + "description": "Set to `true` if the signer views the document", + "type": "boolean", + "example": true, + "readOnly": true + }, + "signer_decision": { + "description": "Final decision made by the signer.", + "type": "object", + "nullable": true, + "properties": { + "type": { + "description": "Type of decision made by the signer.", + "type": "string", + "example": "signed", + "enum": [ + "signed", + "declined" + ] + }, + "finalized_at": { + "description": "Date and Time that the decision was made.", + "type": "string", + "format": "date-time", + "example": "2021-04-26T08:12:13.982Z" + }, + "additional_info": { + "description": "Additional info about the decision, such as the decline reason from the signer.", + "type": "string", + "example": "Requesting changes before signing.", + "nullable": true + } + } + }, + "inputs": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SignRequestSignerInput" + }, + "readOnly": true + }, + "embed_url": { + "description": "URL to direct a signer to for signing", + "type": "string", + "example": "https://example.com", + "nullable": true, + "readOnly": true + }, + "iframeable_embed_url": { + "description": "This URL is specifically designed for\nsigning documents within an HTML `iframe` tag.\nIt will be returned in the response\nonly if the `embed_url_external_user_id`\nparameter was passed in the\n`create Box Sign request` call.", + "type": "string", + "example": "https://app.box.com/embed/sign/document/gfhr4222-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4", + "nullable": true + } + } + } + ], + "required": [ + "email" + ], + "title": "Signer fields for Box Sign request response" + }, + "SignRequestSignerInput": { + "description": "Input created by a Signer on a Sign Request", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/SignRequestPrefillTag" + }, + { + "properties": { + "type": { + "description": "Type of input", + "type": "string", + "example": "text", + "enum": [ + "signature", + "date", + "text", + "checkbox", + "radio", + "dropdown" + ] + }, + "content_type": { + "description": "Content type of input", + "type": "string", + "example": "signature", + "enum": [ + "signature", + "initial", + "stamp", + "date", + "checkbox", + "text", + "full_name", + "first_name", + "last_name", + "company", + "title", + "email", + "attachment", + "radio", + "dropdown" + ] + }, + "page_index": { + "description": "Index of page that the input is on", + "type": "integer", + "example": 4 + }, + "read_only": { + "description": "Whether this input was defined as read-only(immutable by signers) or not", + "type": "boolean", + "example": true + } + } + } + ], + "required": [ + "page_index" + ], + "title": "Sign Request Signer Input" + }, + "SignRequests": { + "description": "A standard representation of a signature request, as returned from any Box Sign\nAPI endpoints by default.", + "type": "object", + "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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of Box Sign requests.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SignRequest" + } + } + } + } + ], + "title": "Box Sign requests", + "x-box-resource-id": "sign_requests", + "x-box-tag": "sign_requests" + }, + "SignTemplate": { + "description": "A Box Sign template object", + "type": "object", + "allOf": [ + { + "properties": { + "type": { + "description": "object type", + "type": "string", + "example": "sign-template", + "enum": [ + "sign-template" + ] + }, + "id": { + "description": "Template identifier.", + "type": "string", + "example": "4206996024-14944f75-c34b-478a-95a1-264b1ff80d35" + }, + "name": { + "description": "The name of the template.", + "type": "string", + "example": "Official contract", + "nullable": true + }, + "email_subject": { + "description": "Subject of signature request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.", + "type": "string", + "example": "Sign Request from Acme", + "nullable": true + }, + "email_message": { + "description": "Message to include in signature request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used.", + "type": "string", + "example": "Hello! Please sign the document below", + "nullable": true + }, + "days_valid": { + "description": "Set the number of days after which the created signature request will automatically expire if not completed. By default, we do not apply any expiration date on signature requests, and the signature request does not expire.", + "type": "integer", + "example": 2, + "maximum": 730, + "minimum": 0, + "nullable": true + }, + "parent_folder": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The destination folder to place final, signed document and signing\nlog. Only `ID` and `type` fields are required. The root folder,\nfolder ID `0`, cannot be used." + } + ] + }, + "source_files": { + "description": "List of files to create a signing document from. Only the ID and type fields are required for each file.", + "type": "array", + "items": { + "$ref": "#/components/schemas/File--Mini" + } + }, + "are_fields_locked": { + "description": "Indicates if the template input fields are editable or not.", + "type": "boolean", + "example": false + }, + "are_options_locked": { + "description": "Indicates if the template document options are editable or not, for example renaming the document.", + "type": "boolean", + "example": true + }, + "are_recipients_locked": { + "description": "Indicates if the template signers are editable or not.", + "type": "boolean", + "example": false + }, + "are_email_settings_locked": { + "description": "Indicates if the template email settings are editable or not.", + "type": "boolean", + "example": true + }, + "are_files_locked": { + "description": "Indicates if the template files are editable or not. This includes deleting or renaming template files.", + "type": "boolean", + "example": true + }, + "signers": { + "description": "Array of signers for the template.\n\n**Note**: It may happen that some signers specified in the template belong to conflicting [segments](r://shield-information-barrier-segment-member) (user groups).\nThis means that due to the security policies, users are assigned to segments to prevent exchanges or communication that could lead to ethical conflicts.\nIn such a case, an attempt to send a sign request based on a template that lists signers in conflicting segments will result in an error.\n\nRead more about [segments and ethical walls](https://support.box.com/hc/en-us/articles/9920431507603-Understanding-Information-Barriers#h_01GFVJEHQA06N7XEZ4GCZ9GFAQ).", + "type": "array", + "items": { + "$ref": "#/components/schemas/TemplateSigner" + } + }, + "additional_info": { + "description": "Additional information on which fields are required and which fields are not editable.", + "type": "object", + "properties": { + "non_editable": { + "description": "Non editable fields.", + "type": "array", + "items": { + "type": "string", + "enum": [ + "email_subject", + "email_message", + "name", + "days_valid", + "signers", + "source_files" + ] + }, + "example": [ + "email_subject", + "name" + ] + }, + "required": { + "description": "Required fields.", + "type": "object", + "properties": { + "signers": { + "description": "Required signer fields.", + "type": "array", + "items": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "email" + ] + }, + "example": [ + "email" + ] + }, + "example": [ + [ + "email" + ], + [ + "email" + ] + ] + } + } + } + } + }, + "ready_sign_link": { + "description": "Box's ready-sign link feature enables you to create a link to a signature request that you've created from a template. Use this link when you want to post a signature request on a public form — such as an email, social media post, or web page — without knowing who the signers will be. Note: The ready-sign link feature is limited to Enterprise Plus customers and not available to Box Verified Enterprises.", + "type": "object", + "nullable": true, + "properties": { + "url": { + "description": "The URL that can be sent to signers.", + "type": "string", + "example": "\"https://app.box.com/sign/\nready-sign-link/a1cdf2c7-fa81-4a67-8163-1e5f4dbe5178\"" + }, + "name": { + "description": "Request name.", + "type": "string", + "example": "Official contract", + "nullable": true + }, + "instructions": { + "description": "Extra instructions for all signers.", + "type": "string", + "example": "Hello! Please sign the document below", + "nullable": true + }, + "folder_id": { + "description": "The destination folder to place final,\nsigned document and signing\nlog. Only `ID` and `type` fields are required.\nThe root folder,\nfolder ID `0`, cannot be used.", + "type": "string", + "example": "12345", + "nullable": true + }, + "is_notification_disabled": { + "description": "Whether to disable notifications when\na signer has signed.", + "type": "boolean", + "example": true + }, + "is_active": { + "description": "Whether the ready sign link is enabled or not.", + "type": "boolean", + "example": false + } + } + }, + "custom_branding": { + "description": "Custom branding applied to notifications\nand signature requests.", + "type": "object", + "nullable": true, + "properties": { + "company_name": { + "description": "Name of the company", + "type": "string", + "example": "Corporation inc.", + "nullable": true + }, + "logo_uri": { + "description": "Custom branding logo URI in the form of a base64 image.", + "type": "string", + "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA\nAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A\n8AAQUBAScY42YAAAAASUVORK5CYII=", + "nullable": true + }, + "branding_color": { + "description": "Custom branding color in hex.", + "type": "string", + "example": "9E5E6F", + "nullable": true + }, + "email_footer_text": { + "description": "Content of the email footer.", + "type": "string", + "example": "Contact email email@mail.com", + "nullable": true + } + } + } + } + } + ], + "title": "Box Sign template", + "x-box-resource-id": "sign_template", + "x-box-tag": "sign_templates" + }, + "SignTemplates": { + "description": "A list of templates, as returned from any Box Sign\nAPI endpoints by default.", + "type": "object", + "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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of templates.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SignTemplate" + } + } + } + } + ], + "title": "Box Sign templates", + "x-box-resource-id": "sign_templates", + "x-box-tag": "sign_templates" + }, + "SkillCardsMetadata": { + "description": "The metadata assigned to a using for Box skills.", + "type": "object", + "properties": { + "$canEdit": { + "description": "Whether the user can edit this metadata", + "type": "boolean", + "example": true + }, + "$id": { + "description": "A UUID to identify the metadata object", + "type": "string", + "format": "uuid", + "example": "01234500-12f1-1234-aa12-b1d234cb567e", + "maxLength": 36 + }, + "$parent": { + "description": "An ID for the parent folder", + "type": "string", + "example": "folder_59449484661," + }, + "$scope": { + "description": "An ID for the scope in which this template\nhas been applied", + "type": "string", + "example": "enterprise_27335" + }, + "$template": { + "description": "The name of the template", + "type": "string", + "example": "properties" + }, + "$type": { + "description": "A unique identifier for the \"type\" of this instance. This is an internal\nsystem property and should not be used by a client application.", + "type": "string", + "example": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0" + }, + "$typeVersion": { + "description": "The last-known version of the template of the object. This is an internal\nsystem property and should not be used by a client application.", + "type": "integer", + "example": 2 + }, + "$version": { + "description": "The version of the metadata object. Starts at 0 and increases every time\na user-defined property is modified.", + "type": "integer", + "example": 1 + }, + "cards": { + "description": "A list of Box Skill cards that have been applied to this file.", + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/KeywordSkillCard" + }, + { + "$ref": "#/components/schemas/TimelineSkillCard" + }, + { + "$ref": "#/components/schemas/TranscriptSkillCard" + }, + { + "$ref": "#/components/schemas/StatusSkillCard" + } + ] + } + } + }, + "title": "Skills metadata instance", + "x-box-resource-id": "skill_cards_metadata", + "x-box-tag": "skills" + }, + "SkillInvocation": { + "description": "The payload of a Box skill as sent to a skill's\n`invocation_url`.", + "type": "object", + "properties": { + "type": { + "description": "`skill_invocation`", + "type": "string", + "example": "skill_invocation", + "enum": [ + "skill_invocation" + ] + }, + "id": { + "description": "Unique identifier for the invocation request.", + "type": "string", + "example": "fd1d2e53-35f5-41fb-9c25-4ba326daf2f9_341016304" + }, + "skill": { + "allOf": [ + { + "title": "Skill", + "type": "object", + "description": "An object representing a skill", + "properties": { + "id": { + "description": "The unique identifier for this skill", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`skill`", + "type": "string", + "example": "skill", + "enum": [ + "skill" + ] + }, + "name": { + "description": "The name of the skill", + "type": "string", + "example": "Hello World Skill" + }, + "api_key": { + "description": "The client ID of the application", + "type": "string", + "example": "hxel2s12wd2h9r8ne103c4gjbqefofih" + } + } + }, + { + "description": "The skill that triggered this invocation" + } + ] + }, + "token": { + "description": "The read-only and read-write access tokens for this item", + "type": "object", + "properties": { + "read": { + "description": "The basics of an access token", + "type": "object", + "properties": { + "access_token": { + "description": "The requested access token.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + }, + "expires_in": { + "description": "The time in seconds by which this token will expire.", + "type": "integer", + "format": "int64", + "example": 3600 + }, + "token_type": { + "description": "The type of access token returned.", + "type": "string", + "example": "bearer", + "enum": [ + "bearer" + ] + }, + "restricted_to": { + "description": "The permissions that this access token permits,\nproviding a list of resources (files, folders, etc)\nand the scopes permitted for each of those resources.", + "type": "string", + "example": "[{\"scope\":\"gcm\"}, {\"scope\":\"item_upload\",\"object_id\":933941692081,\"object_type\":\"file\"}, {\"scope\":\"manage_skill_invocations\"}]" + } + } + }, + "write": { + "description": "The basics of an access token", + "type": "object", + "properties": { + "access_token": { + "description": "The requested access token.", + "type": "string", + "format": "token", + "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" + }, + "expires_in": { + "description": "The time in seconds by which this token will expire.", + "type": "integer", + "format": "int64", + "example": 3600 + }, + "token_type": { + "description": "The type of access token returned.", + "type": "string", + "example": "bearer", + "enum": [ + "bearer" + ] + }, + "restricted_to": { + "description": "The permissions that this access token permits,\nproviding a list of resources (files, folders, etc)\nand the scopes permitted for each of those resources.", + "type": "string", + "example": "[{\"scope\":\"gcm\"}, {\"scope\":\"item_upload\",\"object_id\":933941692081,\"object_type\":\"file\"}, {\"scope\":\"manage_skill_invocations\"}]" + } + } + } + } + }, + "status": { + "description": "The details status of this event.", + "type": "object", + "properties": { + "state": { + "description": "The state of this event.\n\n* `invoked` - Triggered the skill with event details to start\n applying skill on the file.\n* `processing` - Currently processing.\n* `success` - Completed processing with a success.\n* `transient_failure` - Encountered an issue which can be\n retried.\n* `permanent_failure` - Encountered a permanent issue and\n retry would not help.", + "type": "string", + "example": "invoked", + "enum": [ + "invoked", + "processing", + "success", + "transient_failure", + "permanent_failure" + ] + }, + "message": { + "description": "Status information", + "type": "string", + "example": "Example" + }, + "error_code": { + "description": "Error code information, if error occurred.", + "type": "string", + "example": "400" + }, + "additional_info": { + "description": "Additional status information.", + "type": "string", + "example": "Example" + } + } + }, + "created_at": { + "description": "The time this invocation was created.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "trigger": { + "description": "Action that triggered the invocation", + "type": "string", + "example": "FILE_CONTENT" + }, + "enterprise": { + "allOf": [ + { + "title": "Enterprise", + "type": "object", + "description": "A representation of a Box enterprise", + "properties": { + "id": { + "description": "The unique identifier for this enterprise.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`enterprise`", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise" + ] + }, + "name": { + "description": "The name of the enterprise", + "type": "string", + "example": "Acme Inc." + } + } + }, + { + "description": "The enterprise that this invocation was triggered for" + } + ] + }, + "source": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/File" + }, + { + "$ref": "#/components/schemas/Folder" + } + ] + }, + { + "description": "The item that caused the invocation to trigger" + } + ] + }, + "event": { + "allOf": [ + { + "$ref": "#/components/schemas/Event" + }, + { + "description": "The event that triggered this invocation" + } + ] + } + }, + "title": "Skill webhook payload", + "x-box-resource-id": "skill_invocation", + "x-box-tag": "skills" + }, + "StatusSkillCard": { + "description": "A Box Skill metadata card that puts a status message in the metadata sidebar.", + "type": "object", + "properties": { + "created_at": { + "description": "The optional date and time this card was created at.", + "type": "string", + "format": "date-time", + "example": "2018-04-13T13:53:23-07:00" + }, + "type": { + "description": "`skill_card`", + "type": "string", + "example": "skill_card", + "enum": [ + "skill_card" + ] + }, + "skill_card_type": { + "description": "`status`", + "type": "string", + "example": "status", + "enum": [ + "status" + ] + }, + "skill_card_title": { + "description": "The title of the card.", + "type": "object", + "properties": { + "code": { + "description": "An optional identifier for the title.", + "type": "string", + "example": "status" + }, + "message": { + "description": "The actual title to show in the UI.", + "type": "string", + "example": "Status" + } + }, + "required": [ + "message" + ] + }, + "status": { + "description": "Sets the status of the skill. This can be used to show a message to the user while the Skill is processing the data, or if it was not able to process the file.", + "type": "object", + "properties": { + "code": { + "description": "A code for the status of this Skill invocation. By\ndefault each of these will have their own accompanied\nmessages. These can be adjusted by setting the `message`\nvalue on this object.", + "type": "string", + "example": "success", + "enum": [ + "invoked", + "processing", + "success", + "transient_failure", + "permanent_failure" + ] + }, + "message": { + "description": "A custom message that can be provided with this status.\nThis will be shown in the web app to the end user.", + "type": "string", + "example": "We're preparing to process your file. Please hold on!" + } + }, + "required": [ + "code" + ] + }, + "skill": { + "description": "The service that applied this metadata.", + "type": "object", + "properties": { + "type": { + "description": "`service`", + "type": "string", + "example": "service", + "enum": [ + "service" + ] + }, + "id": { + "description": "A custom identifier that represent the service that\napplied this metadata.", + "type": "string", + "example": "image-recognition-service" + } + }, + "required": [ + "type", + "id" + ] + }, + "invocation": { + "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", + "type": "object", + "properties": { + "type": { + "description": "`skill_invocation`", + "type": "string", + "example": "skill_invocation", + "enum": [ + "skill_invocation" + ] + }, + "id": { + "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.", + "type": "string", + "example": "image-recognition-service-123" + } + }, + "required": [ + "type", + "id" + ] + } + }, + "required": [ + "type", + "skill_card_type", + "skill", + "invocation", + "status" + ], + "title": "Status Skill Card", + "x-box-resource-id": "status_skill_card", + "x-box-tag": "skills" + }, + "StoragePolicies": { + "description": "A list of storage policies.", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of storage policies", + "type": "array", + "items": { + "$ref": "#/components/schemas/StoragePolicy" + } + } + } + } + ], + "title": "Storage policies", + "x-box-resource-id": "storage_policies", + "x-box-tag": "storage_policies" + }, + "StoragePolicy": { + "description": "The Storage Policy object describes the storage zone.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/StoragePolicy--Mini" + }, + { + "properties": { + "name": { + "description": "A descriptive name of the region", + "type": "string", + "example": "Montreal / Dublin" + } + } + } + ], + "title": "Storage policy", + "x-box-resource-id": "storage_policy", + "x-box-variant": "standard" + }, + "StoragePolicy--Mini": { + "description": "A mini description of a Storage Policy object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this storage policy", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`storage_policy`", + "type": "string", + "example": "storage_policy", + "enum": [ + "storage_policy" + ] + } + }, + "required": [ + "id", + "type" + ], + "title": "Storage policy (Mini)", + "x-box-resource-id": "storage_policy--mini", + "x-box-tag": "storage_policies", + "x-box-variant": "mini", + "x-box-variants": [ + "standard", + "mini" + ] + }, + "StoragePolicyAssignment": { + "description": "The assignment of a storage policy to a user or enterprise", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for a storage policy assignment.", + "type": "string", + "example": "ZW50ZXJwcmlzZV8xMjM0NTY3ODkw" + }, + "type": { + "description": "`storage_policy_assignment`", + "type": "string", + "example": "storage_policy_assignment", + "enum": [ + "storage_policy_assignment" + ] + }, + "storage_policy": { + "allOf": [ + { + "$ref": "#/components/schemas/StoragePolicy--Mini" + }, + { + "description": "The assigned storage policy" + } + ] + }, + "assigned_to": { + "allOf": [ + { + "title": "Reference", + "description": "The bare basic reference for an object", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this object", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "The type for this object", + "type": "string", + "example": "file" + } + } + }, + { + "description": "The enterprise or use the policy is assigned to" + } + ] + } + }, + "required": [ + "id", + "type" + ], + "title": "Storage policy assignment", + "x-box-resource-id": "storage_policy_assignment", + "x-box-tag": "storage_policy_assignments" + }, + "StoragePolicyAssignments": { + "description": "A list of storage policy assignments.", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of storage policy assignments", + "type": "array", + "items": { + "$ref": "#/components/schemas/StoragePolicyAssignment" + } + } + } + } + ], + "title": "Storage policy assignments", + "x-box-resource-id": "storage_policy_assignments", + "x-box-tag": "storage_policy_assignments" + }, + "Task": { + "description": "A task allows for file-centric workflows within Box. Users can\ncreate tasks on files and assign them to other users for them to complete the\ntasks.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this task", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`task`", + "type": "string", + "example": "task", + "enum": [ + "task" + ] + }, + "item": { + "allOf": [ + { + "$ref": "#/components/schemas/File--Mini" + }, + { + "description": "The file associated with the task" + } + ] + }, + "due_at": { + "description": "When the task is due", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "action": { + "description": "The type of task the task assignee will be prompted to\nperform.", + "type": "string", + "example": "review", + "enum": [ + "review", + "complete" + ] + }, + "message": { + "description": "A message that will be included with the task", + "type": "string", + "example": "Legal review" + }, + "task_assignment_collection": { + "allOf": [ + { + "$ref": "#/components/schemas/TaskAssignments" + }, + { + "description": "A collection of task assignment objects\nassociated with the task" + } + ] + }, + "is_completed": { + "description": "Whether the task has been completed", + "type": "boolean", + "example": true + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created the task" + } + ] + }, + "created_at": { + "description": "When the task object was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "completion_rule": { + "description": "Defines which assignees need to complete this task before the task\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.", + "type": "string", + "example": "all_assignees", + "enum": [ + "all_assignees", + "any_assignee" + ] + } + }, + "title": "Task", + "x-box-resource-id": "task", + "x-box-tag": "tasks" + }, + "TaskAssignment": { + "description": "A task assignment defines which task is assigned to which user to complete.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this task assignment", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`task_assignment`", + "type": "string", + "example": "task_assignment", + "enum": [ + "task_assignment" + ] + }, + "item": { + "allOf": [ + { + "$ref": "#/components/schemas/File--Mini" + }, + { + "description": "The file that the task has been assigned to." + } + ] + }, + "assigned_to": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user that the task has been assigned to." + } + ] + }, + "message": { + "description": "A message that will is included with the task\nassignment. This is visible to the assigned user in the web and mobile\nUI.", + "type": "string", + "example": "Please review" + }, + "completed_at": { + "description": "The date at which this task assignment was\ncompleted. This will be `null` if the task is not completed yet.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "assigned_at": { + "description": "The date at which this task was assigned to the user.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "reminded_at": { + "description": "The date at which the assigned user was reminded of this task\nassignment.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "resolution_state": { + "description": "The current state of the assignment. The available states depend on\nthe `action` value of the task object.", + "type": "string", + "example": "incomplete", + "enum": [ + "completed", + "incomplete", + "approved", + "rejected" + ] + }, + "assigned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who assigned this task." + } + ] + } + }, + "title": "Task assignment", + "x-box-resource-id": "task_assignment", + "x-box-tag": "task_assignments" + }, + "TaskAssignments": { + "description": "A list of task assignments", + "type": "object", + "properties": { + "total_count": { + "description": "The total number of items in this collection.", + "type": "integer", + "format": "int64", + "example": 100 + }, + "entries": { + "description": "A list of task assignments", + "type": "array", + "items": { + "$ref": "#/components/schemas/TaskAssignment" + } + } + }, + "title": "Task assignments", + "x-box-resource-id": "task_assignments", + "x-box-tag": "task_assignments" + }, + "Tasks": { + "description": "A list of tasks", + "type": "object", + "properties": { + "total_count": { + "description": "One greater than the offset of the last entry in the entire collection.\nThe total number of entries in the collection may be less than\n`total_count`.", + "type": "integer", + "format": "int64", + "example": 5000 + }, + "entries": { + "description": "A list of tasks", + "type": "array", + "items": { + "$ref": "#/components/schemas/Task" + } + } + }, + "title": "Tasks", + "x-box-resource-id": "tasks", + "x-box-tag": "tasks" + }, + "TemplateSigner": { + "description": "The schema for a Signer for Templates", + "type": "object", + "allOf": [ + { + "properties": { + "inputs": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TemplateSignerInput" + }, + "readOnly": true + }, + "email": { + "description": "Email address of the signer", + "type": "string", + "example": "example@mail.com", + "nullable": true + }, + "role": { + "description": "Defines the role of the signer in the signature request. A role of\n`signer` needs to sign the document, a role `approver`\napproves the document and\na `final_copy_reader` role only\nreceives the final signed document and signing log.", + "type": "string", + "example": "signer", + "default": "signer", + "enum": [ + "signer", + "approver", + "final_copy_reader" + ] + }, + "is_in_person": { + "description": "Used in combination with an embed URL for a sender.\nAfter the sender signs, they will be\nredirected to the next `in_person` signer.", + "type": "boolean", + "example": true + }, + "order": { + "description": "Order of the signer", + "type": "integer", + "example": 2, + "minimum": 0 + }, + "signer_group_id": { + "description": "If provided, this value points signers that are assigned the same inputs and belongs to same signer group.\nA signer group is not a Box Group. It is an entity that belongs to the template itself and can only be used\nwithin Box Sign requests created from it.", + "type": "string", + "example": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7", + "nullable": true + }, + "label": { + "description": "A placeholder label for the signer set by the template creator to differentiate between signers.", + "type": "string", + "example": "Jane Doe", + "nullable": true + }, + "public_id": { + "description": "An identifier for the signer. This can be used to identify a signer within the template.", + "type": "string", + "example": "RJZYYVPR" + } + } + } + ], + "title": "Signer fields for Templates" + }, + "TemplateSignerInput": { + "description": "Input created by a Signer on a Template", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/SignRequestPrefillTag" + }, + { + "properties": { + "type": { + "description": "Type of input", + "type": "string", + "example": "text", + "enum": [ + "signature", + "date", + "text", + "checkbox", + "attachment", + "radio", + "dropdown" + ] + }, + "content_type": { + "description": "Content type of input", + "type": "string", + "example": "text", + "enum": [ + "signature", + "initial", + "stamp", + "date", + "checkbox", + "text", + "full_name", + "first_name", + "last_name", + "company", + "title", + "email", + "attachment", + "radio", + "dropdown" + ] + }, + "is_required": { + "description": "Whether or not the input is required.", + "type": "boolean", + "example": true + }, + "page_index": { + "description": "Index of page that the input is on.", + "type": "integer", + "example": 4 + }, + "document_id": { + "description": "Document identifier.", + "type": "string", + "example": "123075213-eb54b537-8b25-445e-87c1-5a1c67d8cbd7", + "nullable": true + }, + "dropdown_choices": { + "description": "When the input is of the type `dropdown` this values will be filled with all the dropdown options.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "Yes", + "No", + "Maybe" + ], + "nullable": true + }, + "group_id": { + "description": "When the input is of type `radio` they can be grouped to gather with this identifier.", + "type": "string", + "example": "da317330-225a-4c72-89ad-0d6dcaaf4df6", + "nullable": true + }, + "coordinates": { + "description": "Where the input is located on a page.", + "type": "object", + "properties": { + "x": { + "description": "Relative x coordinate to the page the input is on, ranging from 0 to 1.", + "type": "number", + "example": 0.672258592471358 + }, + "y": { + "description": "Relative y coordinate to the page the input is on, ranging from 0 to 1.", + "type": "number", + "example": 0.18654283173599448 + } + } + }, + "dimensions": { + "description": "The size of the input.", + "type": "object", + "properties": { + "width": { + "description": "Relative width to the page the input is on, ranging from 0 to 1.", + "type": "number", + "example": 0.2618657937806874 + }, + "height": { + "description": "Relative height to the page the input is on, ranging from 0 to 1.", + "type": "number", + "example": 0.05311728090109673 + } + } + }, + "label": { + "description": "The label field is used especially for text, attachment, radio, and checkbox type inputs.", + "type": "string", + "example": "Legal name", + "nullable": true + }, + "read_only": { + "description": "Whether this input was defined as read-only(immutable by signers) or not", + "type": "boolean", + "example": true + } + } + } + ], + "required": [ + "page_index" + ], + "title": "Template Signer Input" + }, + "TermsOfService": { + "description": "The root-level record that is supposed to represent a\nsingle Terms of Service.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/TermsOfService--Base" + }, + { + "properties": { + "status": { + "description": "Whether these terms are enabled or not", + "type": "string", + "example": "enabled", + "enum": [ + "enabled", + "disabled" + ] + }, + "enterprise": { + "allOf": [ + { + "title": "Enterprise", + "type": "object", + "description": "A representation of a Box enterprise", + "properties": { + "id": { + "description": "The unique identifier for this enterprise.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`enterprise`", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise" + ] + }, + "name": { + "description": "The name of the enterprise", + "type": "string", + "example": "Acme Inc." + } + } + }, + { + "description": "The enterprise these terms apply to" + } + ] + }, + "tos_type": { + "description": "Whether to apply these terms to managed users or external users", + "type": "string", + "example": "managed", + "enum": [ + "managed", + "external" + ] + }, + "text": { + "description": "The text for your terms and conditions. This text could be\nempty if the `status` is set to `disabled`.", + "type": "string", + "example": "By using this service, you agree to ..." + }, + "created_at": { + "description": "When the legal item was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When the legal item was modified.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + } + } + ], + "title": "Terms of service", + "x-box-resource-id": "terms_of_service", + "x-box-variant": "standard" + }, + "TermsOfService--Base": { + "description": "The root-level record that is supposed to represent a\nsingle Terms of Service.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this terms of service.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`terms_of_service`", + "type": "string", + "example": "terms_of_service", + "enum": [ + "terms_of_service" + ] + } + }, + "required": [ + "id", + "type" + ], + "title": "Terms of service (Base)", + "x-box-resource-id": "terms_of_service--base", + "x-box-tag": "terms_of_services", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard" + ] + }, + "TermsOfServiceUserStatus": { + "description": "The association between a Terms of Service and a user", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this terms of service user status", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`terms_of_service_user_status`", + "type": "string", + "example": "terms_of_service_user_status", + "enum": [ + "terms_of_service_user_status" + ] + }, + "tos": { + "allOf": [ + { + "$ref": "#/components/schemas/TermsOfService--Base" + }, + { + "description": "The terms of service" + } + ] + }, + "user": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user" + } + ] + }, + "is_accepted": { + "description": "If the user has accepted the terms of services", + "type": "boolean", + "example": true + }, + "created_at": { + "description": "When the legal item was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When the legal item was modified.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + }, + "required": [ + "id", + "type" + ], + "title": "Terms of service user status", + "x-box-resource-id": "terms_of_service_user_status", + "x-box-tag": "terms_of_service_user_statuses" + }, + "TermsOfServiceUserStatuses": { + "description": "A list of terms of service user statuses", + "type": "object", + "properties": { + "total_count": { + "description": "The total number of objects.", + "type": "integer", + "format": "int64", + "example": 2 + }, + "entries": { + "description": "A list of terms of service user statuses", + "type": "array", + "items": { + "$ref": "#/components/schemas/TermsOfServiceUserStatus" + } + } + }, + "title": "Terms of service user statuses", + "x-box-resource-id": "terms_of_services_user_statuses", + "x-box-tag": "terms_of_service_user_statuses" + }, + "TermsOfServices": { + "description": "A list of terms of services", + "type": "object", + "properties": { + "total_count": { + "description": "The total number of objects.", + "type": "integer", + "format": "int64", + "example": 2 + }, + "entries": { + "description": "A list of terms of service objects", + "type": "array", + "items": { + "$ref": "#/components/schemas/TermsOfService" + } + } + }, + "title": "Terms of services", + "x-box-resource-id": "terms_of_services", + "x-box-tag": "terms_of_services" + }, + "TimelineSkillCard": { + "description": "A Box Skill metadata card that places a list of images on a\ntimeline.", + "type": "object", + "properties": { + "created_at": { + "description": "The optional date and time this card was created at.", + "type": "string", + "format": "date-time", + "example": "2018-04-13T13:53:23-07:00" + }, + "type": { + "description": "`skill_card`", + "type": "string", + "example": "skill_card", + "enum": [ + "skill_card" + ] + }, + "skill_card_type": { + "description": "`timeline`", + "type": "string", + "example": "timeline", + "enum": [ + "timeline" + ] + }, + "skill_card_title": { + "description": "The title of the card.", + "type": "object", + "properties": { + "code": { + "description": "An optional identifier for the title.", + "type": "string", + "example": "Faces" + }, + "message": { + "description": "The actual title to show in the UI.", + "type": "string", + "example": "Faces" + } + }, + "required": [ + "message" + ] + }, + "skill": { + "description": "The service that applied this metadata.", + "type": "object", + "properties": { + "type": { + "description": "`service`", + "type": "string", + "example": "service", + "enum": [ + "service" + ] + }, + "id": { + "description": "A custom identifier that represent the service that\napplied this metadata.", + "type": "string", + "example": "image-recognition-service" + } + }, + "required": [ + "type", + "id" + ] + }, + "invocation": { + "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", + "type": "object", + "properties": { + "type": { + "description": "`skill_invocation`", + "type": "string", + "example": "skill_invocation", + "enum": [ + "skill_invocation" + ] + }, + "id": { + "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.", + "type": "string", + "example": "image-recognition-service-123" + } + }, + "required": [ + "type", + "id" + ] + }, + "duration": { + "description": "An total duration in seconds of the timeline.", + "type": "integer", + "example": 1000 + }, + "entries": { + "description": "A list of entries on the timeline.", + "type": "array", + "items": { + "type": "object", + "description": "An single item that's placed on multiple items on the timeline.", + "properties": { + "text": { + "description": "The text of the entry. This would be the display\nname for an item being placed on the timeline, for example the name\nof the person who was detected in a video.", + "type": "string", + "example": "John" + }, + "appears": { + "description": "Defines a list of timestamps for when this item should appear on the\ntimeline.", + "type": "array", + "items": { + "type": "object", + "description": "The timestamp for an entry.", + "properties": { + "start": { + "description": "The time in seconds when an\nentry should start appearing on a timeline.", + "type": "integer", + "example": 1 + }, + "end": { + "description": "The time in seconds when an\nentry should stop appearing on a timeline.", + "type": "integer", + "example": 20 + } + } + }, + "required": [ + "start", + "end" + ] + }, + "image_url": { + "description": "The image to show on a for an entry that appears\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.", + "type": "string", + "example": "https://example.com/image1.jpg" + } + } + } + } + }, + "required": [ + "type", + "skill_card_type", + "skill", + "invocation", + "entries" + ], + "title": "Timeline Skill Card", + "x-box-resource-id": "timeline_skill_card", + "x-box-tag": "skills" + }, + "TrackingCode": { + "description": "Tracking codes allow an admin to generate reports from the admin console\nand assign an attribute to a specific group of users.\nThis setting must be enabled for an enterprise before it can be used.", + "type": "object", + "properties": { + "type": { + "description": "`tracking_code`", + "type": "string", + "example": "tracking_code", + "enum": [ + "tracking_code" + ] + }, + "name": { + "description": "The name of the tracking code, which must be preconfigured in\nthe Admin Console", + "type": "string", + "example": "department" + }, + "value": { + "description": "The value of the tracking code", + "type": "string", + "example": "Sales" + } + }, + "title": "Tracking code" + }, + "TranscriptSkillCard": { + "description": "A Box Skill metadata card that adds a transcript to a file.", + "type": "object", + "properties": { + "created_at": { + "description": "The optional date and time this card was created at.", + "type": "string", + "format": "date-time", + "example": "2018-04-13T13:53:23-07:00" + }, + "type": { + "description": "`skill_card`", + "type": "string", + "example": "skill_card", + "enum": [ + "skill_card" + ] + }, + "skill_card_type": { + "description": "`transcript`", + "type": "string", + "example": "transcript", + "enum": [ + "transcript" + ] + }, + "skill_card_title": { + "description": "The title of the card.", + "type": "object", + "properties": { + "code": { + "description": "An optional identifier for the title.", + "type": "string", + "example": "my_transcripts" + }, + "message": { + "description": "The actual title to show in the UI.", + "type": "string", + "example": "My Transcripts" + } + }, + "required": [ + "message" + ] + }, + "skill": { + "description": "The service that applied this metadata.", + "type": "object", + "properties": { + "type": { + "description": "`service`", + "type": "string", + "example": "service", + "enum": [ + "service" + ] + }, + "id": { + "description": "A custom identifier that represent the service that\napplied this metadata.", + "type": "string", + "example": "transciption-service" + } + }, + "required": [ + "type", + "id" + ] + }, + "invocation": { + "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", + "type": "object", + "properties": { + "type": { + "description": "`skill_invocation`", + "type": "string", + "example": "skill_invocation", + "enum": [ + "skill_invocation" + ] + }, + "id": { + "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.", + "type": "string", + "example": "transciption-service-123" + } + }, + "required": [ + "type", + "id" + ] + }, + "duration": { + "description": "An optional total duration in seconds.\n\nUsed with a `skill_card_type` of `transcript` or\n`timeline`.", + "type": "integer", + "example": 1000 + }, + "entries": { + "description": "An list of entries for the card. This represents the individual entries of\nthe transcription.", + "type": "array", + "items": { + "type": "object", + "description": "An entry in the `entries` attribute of a metadata card", + "properties": { + "text": { + "description": "The text of the entry. This would be the transcribed text assigned\nto the entry on the timeline.", + "type": "string", + "example": "Hi, and welcome to this video..." + }, + "appears": { + "description": "Defines when a transcribed bit of text appears. This only includes a\nstart time and no end time.", + "type": "array", + "items": { + "type": "object", + "description": "The timestamp for an entry.", + "properties": { + "start": { + "description": "The time in seconds when an\nentry should start appearing on a timeline.", + "type": "integer", + "example": 1 + } + } + }, + "required": [ + "start" + ] + } + } + } + } + }, + "required": [ + "type", + "skill_card_type", + "skill", + "invocation", + "entries" + ], + "title": "Transcript Skill Card", + "x-box-resource-id": "transcript_skill_card", + "x-box-tag": "skills" + }, + "TrashFile": { + "description": "Represents a trashed file.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\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`.", + "type": "string", + "example": "123456789", + "nullable": false + }, + "etag": { + "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": "string", + "example": "1", + "nullable": true + }, + "type": { + "description": "`file`", + "type": "string", + "example": "file", + "enum": [ + "file" + ], + "nullable": false + }, + "sequence_id": { + "allOf": [ + { + "type": "string", + "example": "3", + "nullable": true, + "description": "A numeric identifier that represents the most recent user event\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." + }, + { + "nullable": false + } + ] + }, + "name": { + "description": "The name of the file", + "type": "string", + "example": "Contract.pdf" + }, + "sha1": { + "description": "The SHA1 hash of the file. This can be used to compare the contents\nof a file on Box with a local file.", + "type": "string", + "format": "digest", + "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37", + "nullable": false + }, + "file_version": { + "allOf": [ + { + "$ref": "#/components/schemas/FileVersion--Mini" + }, + { + "description": "The information about the current version of the file." + } + ] + }, + "description": { + "description": "The optional description of this file", + "type": "string", + "example": "Contract for Q1 renewal", + "maxLength": 256, + "nullable": false + }, + "size": { + "description": "The file size in bytes. Be careful parsing this integer as it can\nget very large and cause an integer overflow.", + "type": "integer", + "example": 629644, + "nullable": false + }, + "path_collection": { + "allOf": [ + { + "title": "Path collection (Trash)", + "description": "A list of parent folders for an item in the trash.", + "type": "object", + "required": [ + "total_count", + "entries" + ], + "properties": { + "total_count": { + "description": "The number of folders in this list.", + "type": "integer", + "format": "int64", + "example": 1, + "nullable": false + }, + "entries": { + "description": "Array of folders for this item's path collection", + "type": "array", + "items": { + "type": "object", + "description": "The parent folder for this item", + "properties": { + "type": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ] + }, + "id": { + "description": "The unique identifier that represent a folder.", + "type": "string", + "example": "123456789" + }, + "sequence_id": { + "description": "This field is null for the Trash folder", + "type": "string", + "example": null, + "nullable": true + }, + "etag": { + "description": "This field is null for the Trash folder", + "type": "string", + "example": null, + "nullable": true + }, + "name": { + "description": "The name of the Trash folder.", + "type": "string", + "example": "Trash", + "nullable": false + } + } + } + } + } + }, + { + "description": "The tree of folders that this file is contained in,\nstarting at the root." + }, + { + "nullable": false + } + ] + }, + "created_at": { + "description": "The date and time when the file was created on Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": false + }, + "modified_at": { + "description": "The date and time when the file was last updated on Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": false + }, + "trashed_at": { + "description": "The time at which this file was put in the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "purged_at": { + "description": "The time at which this file is expected to be purged\nfrom the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "content_created_at": { + "description": "The date and time at which this file was originally\ncreated, which might be before it was uploaded to Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "content_modified_at": { + "description": "The date and time at which this file was last updated,\nwhich might be before it was uploaded to Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created this file" + } + ] + }, + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who last modified this file" + }, + { + "nullable": false + } + ] + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who owns this file" + }, + { + "nullable": false + } + ] + }, + "shared_link": { + "description": "The shared link for this file. This will\nbe `null` if a file has been trashed, since the link will no longer\nbe active.", + "type": "string", + "example": null, + "nullable": true + }, + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The folder that this file is located within." + }, + { + "nullable": true + } + ] + }, + "item_status": { + "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", + "type": "string", + "example": "trashed", + "enum": [ + "active", + "trashed", + "deleted" + ], + "nullable": false + } + }, + "required": [ + "id", + "type", + "sequence_id", + "sha1", + "description", + "size", + "path_collection", + "created_at", + "modified_at", + "modified_by", + "owned_by", + "item_status" + ], + "title": "Trashed File", + "x-box-resource-id": "trash_file", + "x-box-tag": "trashed_files" + }, + "TrashFileRestored": { + "description": "Represents a file restored from the trash.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\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`.", + "type": "string", + "example": "123456789", + "nullable": false + }, + "etag": { + "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": "string", + "example": "1", + "nullable": true + }, + "type": { + "description": "`file`", + "type": "string", + "example": "file", + "enum": [ + "file" + ], + "nullable": false + }, + "sequence_id": { + "allOf": [ + { + "type": "string", + "example": "3", + "nullable": true, + "description": "A numeric identifier that represents the most recent user event\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." + }, + { + "nullable": false + } + ] + }, + "name": { + "description": "The name of the file", + "type": "string", + "example": "Contract.pdf" + }, + "sha1": { + "description": "The SHA1 hash of the file. This can be used to compare the contents\nof a file on Box with a local file.", + "type": "string", + "format": "digest", + "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37", + "nullable": false + }, + "file_version": { + "allOf": [ + { + "$ref": "#/components/schemas/FileVersion--Mini" + }, + { + "description": "The information about the current version of the file." + } + ] + }, + "description": { + "description": "The optional description of this file", + "type": "string", + "example": "Contract for Q1 renewal", + "maxLength": 256, + "nullable": false + }, + "size": { + "description": "The file size in bytes. Be careful parsing this integer as it can\nget very large and cause an integer overflow.", + "type": "integer", + "example": 629644, + "nullable": false + }, + "path_collection": { + "allOf": [ + { + "title": "Path collection", + "description": "A list of parent folders for an item.", + "type": "object", + "required": [ + "total_count", + "entries" + ], + "properties": { + "total_count": { + "description": "The number of folders in this list.", + "type": "integer", + "format": "int64", + "example": 1, + "nullable": false + }, + "entries": { + "description": "The parent folders for this item", + "type": "array", + "items": { + "$ref": "#/components/schemas/Folder--Mini" + }, + "nullable": false + } + } + }, + { + "description": "The tree of folders that this file is contained in,\nstarting at the root." + }, + { + "nullable": false + } + ] + }, + "created_at": { + "description": "The date and time when the file was created on Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": false + }, + "modified_at": { + "description": "The date and time when the file was last updated on Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": false + }, + "trashed_at": { + "description": "The time at which this file was put in the\ntrash - becomes `null` after restore.", + "type": "string", + "example": null, + "nullable": true + }, + "purged_at": { + "description": "The time at which this file is expected to be purged\nfrom the trash - becomes `null` after restore.", + "type": "string", + "example": null, + "nullable": true + }, + "content_created_at": { + "description": "The date and time at which this file was originally\ncreated, which might be before it was uploaded to Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "content_modified_at": { + "description": "The date and time at which this file was last updated,\nwhich might be before it was uploaded to Box.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created this file" + } + ] + }, + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who last modified this file" + }, + { + "nullable": false + } + ] + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who owns this file" + }, + { + "nullable": false + } + ] + }, + "shared_link": { + "description": "The shared link for this file. This will\nbe `null` if a file had been trashed, even though the original shared\nlink does become active again.", + "type": "string", + "example": null, + "nullable": true + }, + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The folder that this file is located within." + }, + { + "nullable": true + } + ] + }, + "item_status": { + "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", + "type": "string", + "example": "active", + "enum": [ + "active", + "trashed", + "deleted" + ], + "nullable": false + } + }, + "required": [ + "id", + "type", + "sequence_id", + "sha1", + "description", + "size", + "path_collection", + "created_at", + "modified_at", + "modified_by", + "owned_by", + "item_status" + ], + "title": "Trashed File (Restored)", + "x-box-resource-id": "trash_file_restored", + "x-box-tag": "trashed_files" + }, + "TrashFolder": { + "description": "Represents a trashed folder.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "type": "string", + "example": "123456789", + "nullable": false + }, + "etag": { + "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": "string", + "example": "1", + "nullable": true + }, + "type": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ], + "nullable": false + }, + "sequence_id": { + "allOf": [ + { + "type": "string", + "example": "3", + "nullable": true, + "description": "A numeric identifier that represents the most recent user event\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." + }, + { + "nullable": false + } + ] + }, + "name": { + "description": "The name of the folder.", + "type": "string", + "example": "Contracts", + "nullable": false + }, + "created_at": { + "description": "The date and time when the folder was created. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "modified_at": { + "description": "The date and time when the folder was last updated. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "description": { + "allOf": [ + { + "type": "string", + "description": "The optional description of this folder", + "maxLength": 256, + "example": "Legal contracts for the new ACME deal", + "nullable": false + }, + { + "nullable": false + } + ] + }, + "size": { + "description": "The folder size in bytes.\n\nBe careful parsing this integer as its\nvalue can get very large.", + "type": "integer", + "format": "int64", + "example": 629644, + "nullable": false + }, + "path_collection": { + "allOf": [ + { + "title": "Path collection (Trash)", + "description": "A list of parent folders for an item in the trash.", + "type": "object", + "required": [ + "total_count", + "entries" + ], + "properties": { + "total_count": { + "description": "The number of folders in this list.", + "type": "integer", + "format": "int64", + "example": 1, + "nullable": false + }, + "entries": { + "description": "Array of folders for this item's path collection", + "type": "array", + "items": { + "type": "object", + "description": "The parent folder for this item", + "properties": { + "type": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ] + }, + "id": { + "description": "The unique identifier that represent a folder.", + "type": "string", + "example": "123456789" + }, + "sequence_id": { + "description": "This field is null for the Trash folder", + "type": "string", + "example": null, + "nullable": true + }, + "etag": { + "description": "This field is null for the Trash folder", + "type": "string", + "example": null, + "nullable": true + }, + "name": { + "description": "The name of the Trash folder.", + "type": "string", + "example": "Trash", + "nullable": false + } + } + } + } + } + }, + { + "description": "The tree of folders that this file is contained in,\nstarting at the root." + }, + { + "nullable": false + } + ] + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created this folder" + }, + { + "nullable": false + } + ] + }, + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who last modified this folder." + }, + { + "nullable": false + } + ] + }, + "trashed_at": { + "description": "The time at which this folder was put in the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "purged_at": { + "description": "The time at which this folder is expected to be purged\nfrom the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "content_created_at": { + "description": "The date and time at which this folder was originally\ncreated.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "content_modified_at": { + "description": "The date and time at which this folder was last updated.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who owns this folder." + }, + { + "nullable": false + } + ] + }, + "shared_link": { + "description": "The shared link for this folder. This will\nbe `null` if a folder has been trashed, since the link will no longer\nbe active.", + "type": "string", + "example": null, + "nullable": true + }, + "folder_upload_email": { + "description": "The folder upload email for this folder. This will\nbe `null` if a folder has been trashed, since the upload will no longer\nwork.", + "type": "string", + "example": null, + "nullable": true + }, + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the\nroot folder or the trash folder." + }, + { + "nullable": true + } + ] + }, + "item_status": { + "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", + "type": "string", + "example": "trashed", + "enum": [ + "active", + "trashed", + "deleted" + ], + "nullable": false + } + }, + "required": [ + "id", + "type", + "name", + "description", + "size", + "path_collection", + "created_by", + "modified_by", + "owned_by", + "item_status" + ], + "title": "Trashed Folder", + "x-box-resource-id": "trash_folder", + "x-box-tag": "trashed_folders" + }, + "TrashFolderRestored": { + "description": "Represents a folder restored from the trash.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\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`.", + "type": "string", + "example": "123456789", + "nullable": false + }, + "etag": { + "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": "string", + "example": "1", + "nullable": true + }, + "type": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ], + "nullable": false + }, + "sequence_id": { + "allOf": [ + { + "type": "string", + "example": "3", + "nullable": true, + "description": "A numeric identifier that represents the most recent user event\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." + }, + { + "nullable": false + } + ] + }, + "name": { + "description": "The name of the folder.", + "type": "string", + "example": "Contracts", + "nullable": false + }, + "created_at": { + "description": "The date and time when the folder was created. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "modified_at": { + "description": "The date and time when the folder was last updated. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "description": { + "allOf": [ + { + "type": "string", + "description": "The optional description of this folder", + "maxLength": 256, + "example": "Legal contracts for the new ACME deal", + "nullable": false + }, + { + "nullable": false + } + ] + }, + "size": { + "description": "The folder size in bytes.\n\nBe careful parsing this integer as its\nvalue can get very large.", + "type": "integer", + "format": "int64", + "example": 629644, + "nullable": false + }, + "path_collection": { + "allOf": [ + { + "title": "Path collection", + "description": "A list of parent folders for an item.", + "type": "object", + "required": [ + "total_count", + "entries" + ], + "properties": { + "total_count": { + "description": "The number of folders in this list.", + "type": "integer", + "format": "int64", + "example": 1, + "nullable": false + }, + "entries": { + "description": "The parent folders for this item", + "type": "array", + "items": { + "$ref": "#/components/schemas/Folder--Mini" + }, + "nullable": false + } + } + }, + { + "description": "The tree of folders that this file is contained in,\nstarting at the root." + }, + { + "nullable": false + } + ] + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created this folder" + }, + { + "nullable": false + } + ] + }, + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who last modified this folder." + }, + { + "nullable": false + } + ] + }, + "trashed_at": { + "description": "The time at which this folder was put in the\ntrash - becomes `null` after restore.", + "type": "string", + "example": null, + "nullable": true + }, + "purged_at": { + "description": "The time at which this folder is expected to be purged\nfrom the trash - becomes `null` after restore.", + "type": "string", + "example": null, + "nullable": true + }, + "content_created_at": { + "description": "The date and time at which this folder was originally\ncreated.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "content_modified_at": { + "description": "The date and time at which this folder was last updated.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who owns this folder." + }, + { + "nullable": false + } + ] + }, + "shared_link": { + "description": "The shared link for this file. This will\nbe `null` if a folder had been trashed, even though the original shared\nlink does become active again.", + "type": "string", + "example": null, + "nullable": true + }, + "folder_upload_email": { + "description": "The folder upload email for this folder. This will\nbe `null` if a folder has been trashed, even though the original upload\nemail does become active again.", + "type": "string", + "example": null, + "nullable": true + }, + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the\nroot folder or the trash folder." + }, + { + "nullable": true + } + ] + }, + "item_status": { + "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.", + "type": "string", + "example": "active", + "enum": [ + "active", + "trashed", + "deleted" + ], + "nullable": false + } + }, + "title": "Trashed Folder (Restored)", + "x-box-resource-id": "trash_folder_restored", + "x-box-tag": "trashed_folders" + }, + "TrashWebLink": { + "description": "Represents a trashed web link.", + "type": "object", + "properties": { + "type": { + "description": "`web_link`", + "type": "string", + "example": "web_link", + "enum": [ + "web_link" + ] + }, + "id": { + "description": "The unique identifier for this web link", + "type": "string", + "example": "11446498" + }, + "sequence_id": { + "allOf": [ + { + "type": "string", + "example": "3", + "nullable": true, + "description": "A numeric identifier that represents the most recent user event\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." + }, + { + "nullable": false + } + ] + }, + "etag": { + "description": "The entity tag of this web link. Used with `If-Match`\nheaders.", + "type": "string", + "example": "1" + }, + "name": { + "description": "The name of the web link", + "type": "string", + "example": "My Bookmark" + }, + "url": { + "description": "The URL this web link points to", + "type": "string", + "example": "https://www.example.com/example/1234" + }, + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The parent object the web link belongs to" + } + ] + }, + "description": { + "description": "The description accompanying the web link. This is\nvisible within the Box web application.", + "type": "string", + "example": "Example page" + }, + "path_collection": { + "allOf": [ + { + "title": "Path collection (Trash)", + "description": "A list of parent folders for an item in the trash.", + "type": "object", + "required": [ + "total_count", + "entries" + ], + "properties": { + "total_count": { + "description": "The number of folders in this list.", + "type": "integer", + "format": "int64", + "example": 1, + "nullable": false + }, + "entries": { + "description": "Array of folders for this item's path collection", + "type": "array", + "items": { + "type": "object", + "description": "The parent folder for this item", + "properties": { + "type": { + "description": "`folder`", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ] + }, + "id": { + "description": "The unique identifier that represent a folder.", + "type": "string", + "example": "123456789" + }, + "sequence_id": { + "description": "This field is null for the Trash folder", + "type": "string", + "example": null, + "nullable": true + }, + "etag": { + "description": "This field is null for the Trash folder", + "type": "string", + "example": null, + "nullable": true + }, + "name": { + "description": "The name of the Trash folder.", + "type": "string", + "example": "Trash", + "nullable": false + } + } + } + } + } + }, + { + "description": "The tree of folders that this web link is contained in,\nstarting at the root." + }, + { + "nullable": false + } + ] + }, + "created_at": { + "description": "When this file was created on Box’s servers.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When this file was last updated on the Box\nservers.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "trashed_at": { + "description": "When this file was last moved to the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "purged_at": { + "description": "When this file will be permanently deleted.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created this web link" + } + ] + }, + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who last modified this web link" + } + ] + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who owns this web link" + } + ] + }, + "shared_link": { + "description": "The shared link for this bookmark. This will\nbe `null` if a bookmark has been trashed, since the link will no longer\nbe active.", + "type": "string", + "example": null, + "nullable": true + }, + "item_status": { + "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", + "type": "string", + "example": "trashed", + "enum": [ + "active", + "trashed", + "deleted" + ] + } + }, + "title": "Trashed Web Link", + "x-box-resource-id": "trash_web_link", + "x-box-tag": "trashed_web_links" + }, + "TrashWebLinkRestored": { + "description": "Represents a web link restored from the trash.", + "type": "object", + "properties": { + "type": { + "description": "`web_link`", + "type": "string", + "example": "web_link", + "enum": [ + "web_link" + ] + }, + "id": { + "description": "The unique identifier for this web link", + "type": "string", + "example": "11446498" + }, + "sequence_id": { + "allOf": [ + { + "type": "string", + "example": "3", + "nullable": true, + "description": "A numeric identifier that represents the most recent user event\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." + }, + { + "nullable": false + } + ] + }, + "etag": { + "description": "The entity tag of this web link. Used with `If-Match`\nheaders.", + "type": "string", + "example": "1" + }, + "name": { + "description": "The name of the web link", + "type": "string", + "example": "My Bookmark" + }, + "url": { + "description": "The URL this web link points to", + "type": "string", + "example": "https://www.example.com/example/1234" + }, + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The parent object the web link belongs to" + } + ] + }, + "description": { + "description": "The description accompanying the web link. This is\nvisible within the Box web application.", + "type": "string", + "example": "Example page" + }, + "path_collection": { + "allOf": [ + { + "title": "Path collection", + "description": "A list of parent folders for an item.", + "type": "object", + "required": [ + "total_count", + "entries" + ], + "properties": { + "total_count": { + "description": "The number of folders in this list.", + "type": "integer", + "format": "int64", + "example": 1, + "nullable": false + }, + "entries": { + "description": "The parent folders for this item", + "type": "array", + "items": { + "$ref": "#/components/schemas/Folder--Mini" + }, + "nullable": false + } + } + }, + { + "description": "The tree of folders that this web link is contained in,\nstarting at the root." + }, + { + "nullable": false + } + ] + }, + "created_at": { + "description": "When this file was created on Box’s servers.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When this file was last updated on the Box\nservers.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "trashed_at": { + "description": "The time at which this bookmark was put in the\ntrash - becomes `null` after restore.", + "type": "string", + "example": null, + "nullable": true + }, + "purged_at": { + "description": "The time at which this bookmark will be permanently\ndeleted - becomes `null` after restore.", + "type": "string", + "example": null, + "nullable": true + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created this web link" + } + ] + }, + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who last modified this web link" + } + ] + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who owns this web link" + } + ] + }, + "shared_link": { + "description": "The shared link for this bookmark. This will\nbe `null` if a bookmark had been trashed, even though the original shared\nlink does become active again.", + "type": "string", + "example": null, + "nullable": true + }, + "item_status": { + "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", + "type": "string", + "example": "trashed", + "enum": [ + "active", + "trashed", + "deleted" + ] + } + }, + "required": [ + "sequence_id", + "path_collection" + ], + "title": "Trashed Web Link (Restored)", + "x-box-resource-id": "trash_web_link_restored", + "x-box-tag": "trashed_web_links" + }, + "UploadPart": { + "description": "The representation of an upload\nsession chunk.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/UploadPart--Mini" + }, + { + "properties": { + "sha1": { + "description": "The SHA1 hash of the chunk.", + "type": "string", + "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc" + } + } + } + ], + "title": "Upload part", + "x-box-resource-id": "upload_part", + "x-box-variant": "standard" + }, + "UploadPart--Mini": { + "description": "The basic representation of an upload\nsession chunk.", + "type": "object", + "properties": { + "part_id": { + "description": "The unique ID of the chunk.", + "type": "string", + "example": "6F2D3486" + }, + "offset": { + "description": "The offset of the chunk within the file\nin bytes. The lower bound of the position\nof the chunk within the file.", + "type": "integer", + "format": "int64", + "example": 16777216 + }, + "size": { + "description": "The size of the chunk in bytes.", + "type": "integer", + "format": "int64", + "example": 3222784 + } + }, + "title": "Upload part (Mini)", + "x-box-resource-id": "upload_part--mini", + "x-box-tag": "chunked_uploads", + "x-box-variant": "mini", + "x-box-variants": [ + "mini", + "standard" + ] + }, + "UploadParts": { + "description": "A list of uploaded chunks for an upload\nsession.", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes pagination", + "properties": { + "total_count": { + "description": "One greater than the offset of the last entry in the entire collection.\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", + "example": 5000 + }, + "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", + "example": 1000 + }, + "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", + "example": 2000 + }, + "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", + "example": "type" + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "ASC", + "enum": [ + "ASC", + "DESC" + ] + } + } + } + } + } + }, + { + "properties": { + "entries": { + "description": "A list of uploaded chunks for an upload\nsession", + "type": "array", + "items": { + "$ref": "#/components/schemas/UploadPart" + } + } + } + } + ], + "title": "Upload parts", + "x-box-resource-id": "upload_parts", + "x-box-tag": "chunked_uploads" + }, + "UploadSession": { + "description": "An upload session for chunk uploading a file.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this session", + "type": "string", + "example": "F971964745A5CD0C001BBE4E58196BFD" + }, + "type": { + "description": "`upload_session`", + "type": "string", + "example": "upload_session", + "enum": [ + "upload_session" + ] + }, + "session_expires_at": { + "description": "The date and time when this session expires.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "part_size": { + "description": "The size in bytes that must be used for all parts of of the\nupload.\n\nOnly the last part is allowed to be of a smaller size.", + "type": "integer", + "format": "int64", + "example": 1024 + }, + "total_parts": { + "description": "The total number of parts expected in this upload session,\nas determined by the file size and part size.", + "type": "integer", + "format": "int32", + "example": 1000 + }, + "num_parts_processed": { + "description": "The number of parts that have been uploaded and processed\nby the server. This starts at `0`.\n\nWhen committing a file files, inspecting this property can\nprovide insight if all parts have been uploaded correctly.", + "type": "integer", + "format": "int32", + "example": 455 + }, + "session_endpoints": { + "allOf": [ + { + "title": "Session endpoints", + "description": "A list of endpoints for a chunked upload session.", + "type": "object", + "properties": { + "upload_part": { + "description": "The URL to upload parts to", + "type": "string", + "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" + }, + "commit": { + "description": "The URL used to commit the file", + "type": "string", + "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit" + }, + "abort": { + "description": "The URL for used to abort the session.", + "type": "string", + "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" + }, + "list_parts": { + "description": "The URL users to list all parts.", + "type": "string", + "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts" + }, + "status": { + "description": "The URL used to get the status of the upload.", + "type": "string", + "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" + }, + "log_event": { + "description": "The URL used to get the upload log from.", + "type": "string", + "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log" + } + } + }, + { + "description": "A list of endpoints for this session." + } + ] + } + }, + "title": "Upload session", + "x-box-resource-id": "upload_session", + "x-box-tag": "chunked_uploads" + }, + "UploadUrl": { + "description": "The details for the upload session for the file.", + "type": "object", + "properties": { + "upload_url": { + "description": "A URL for an upload session that can be used to upload\nthe file.", + "type": "string", + "example": "https://upload-las.app.box.com/api/2.0/files/content?upload_session_id=1234" + }, + "upload_token": { + "description": "An optional access token to use to upload the file", + "type": "string", + "example": "Pc3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQP" + } + }, + "title": "Upload URL", + "x-box-resource-id": "upload_url", + "x-box-tag": "uploads" + }, + "UploadedPart": { + "description": "A chunk of a file uploaded as part of\nan upload session, as returned by some endpoints.", + "type": "object", + "properties": { + "part": { + "$ref": "#/components/schemas/UploadPart" + } + }, + "title": "Uploaded part", + "x-box-resource-id": "uploaded_part", + "x-box-tag": "chunked_uploads" + }, + "User": { + "description": "A standard representation of a user, as returned from any\nuser API endpoints by default", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "properties": { + "created_at": { + "description": "When the user object was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When the user object was last modified", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "language": { + "description": "The language of the user, formatted in modified version of the\n[ISO 639-1](/guides/api-calls/language-codes) format.", + "type": "string", + "example": "en" + }, + "timezone": { + "description": "The user's timezone", + "type": "string", + "format": "timezone", + "example": "Africa/Bujumbura" + }, + "space_amount": { + "description": "The user’s total available space amount in bytes", + "type": "integer", + "format": "int64", + "example": 11345156112 + }, + "space_used": { + "description": "The amount of space in use by the user", + "type": "integer", + "format": "int64", + "example": 1237009912 + }, + "max_upload_size": { + "description": "The maximum individual file size in bytes the user can have", + "type": "integer", + "format": "int64", + "example": 2147483648 + }, + "status": { + "description": "The user's account status", + "type": "string", + "example": "active", + "enum": [ + "active", + "inactive", + "cannot_delete_edit", + "cannot_delete_edit_upload" + ] + }, + "job_title": { + "description": "The user’s job title", + "type": "string", + "example": "CEO", + "maxLength": 100 + }, + "phone": { + "description": "The user’s phone number", + "type": "string", + "example": "6509241374", + "maxLength": 100 + }, + "address": { + "description": "The user’s address", + "type": "string", + "example": "900 Jefferson Ave, Redwood City, CA 94063", + "maxLength": 255 + }, + "avatar_url": { + "description": "URL of the user’s avatar image", + "type": "string", + "example": "https://www.box.com/api/avatar/large/181216415" + }, + "notification_email": { + "description": "An alternate notification email address to which email\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.", + "type": "object", + "nullable": true, + "properties": { + "email": { + "description": "The email address to send the notifications to.", + "type": "string", + "example": "notifications@example.com" + }, + "is_confirmed": { + "description": "Specifies if this email address has been confirmed.", + "type": "boolean", + "example": true + } + } + } + } + } + ], + "title": "User", + "x-box-resource-id": "user", + "x-box-variant": "standard" + }, + "User--Base": { + "description": "A mini representation of a user, used when\nnested within another resource.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this user", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`user`", + "type": "string", + "example": "user", + "enum": [ + "user" + ], + "nullable": false + } + }, + "required": [ + "type", + "id" + ], + "title": "User (Base)", + "x-box-resource-id": "user--base", + "x-box-tag": "users", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard", + "full" + ] + }, + "User--Collaborations": { + "description": "A mini representation of a user, can be returned only when\nthe status is `pending`.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "properties": { + "name": { + "description": "The display name of this user. If the collaboration status is `pending`, an empty string is returned.", + "type": "string", + "example": "Aaron Levie", + "maxLength": 50, + "nullable": false + }, + "login": { + "description": "The primary email address of this user. If the collaboration status is `pending`, an empty string is returned.", + "type": "string", + "format": "email", + "example": "ceo@example.com", + "nullable": false + }, + "is_active": { + "description": "If set to `false`, the user is either deactivated or deleted.", + "type": "boolean", + "example": true + } + } + } + ], + "title": "User (Collaborations)", + "x-box-resource-id": "user_collaborations", + "x-box-variant": "collaborations" + }, + "User--Full": { + "description": "A full representation of a user, as can be returned from any\nuser API endpoint.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/User" + }, + { + "properties": { + "role": { + "description": "The user’s enterprise role", + "type": "string", + "example": "admin", + "enum": [ + "admin", + "coadmin", + "user" + ] + }, + "tracking_codes": { + "description": "Tracking codes allow an admin to generate reports from the\nadmin console and assign an attribute to a specific group\nof users. This setting must be enabled for an enterprise\nbefore it can be used.", + "type": "array", + "items": { + "$ref": "#/components/schemas/TrackingCode" + } + }, + "can_see_managed_users": { + "description": "Whether the user can see other enterprise users in their contact list", + "type": "boolean", + "example": true + }, + "is_sync_enabled": { + "description": "Whether the user can use Box Sync", + "type": "boolean", + "example": true + }, + "is_external_collab_restricted": { + "description": "Whether the user is allowed to collaborate with users outside their\nenterprise", + "type": "boolean", + "example": true + }, + "is_exempt_from_device_limits": { + "description": "Whether to exempt the user from Enterprise device limits", + "type": "boolean", + "example": true + }, + "is_exempt_from_login_verification": { + "description": "Whether the user must use two-factor authentication", + "type": "boolean", + "example": true + }, + "enterprise": { + "allOf": [ + { + "title": "Enterprise", + "type": "object", + "description": "A representation of a Box enterprise", + "properties": { + "id": { + "description": "The unique identifier for this enterprise.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`enterprise`", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise" + ] + }, + "name": { + "description": "The name of the enterprise", + "type": "string", + "example": "Acme Inc." + } + } + }, + { + "description": "Representation of the user’s enterprise" + } + ] + }, + "my_tags": { + "description": "Tags for all files and folders owned by the user. Values returned\nwill only contain tags that were set by the requester.", + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "important" + ] + }, + "hostname": { + "description": "The root (protocol, subdomain, domain) of any links that need to be\ngenerated for the user", + "type": "string", + "example": "https://example.app.box.com/" + }, + "is_platform_access_only": { + "description": "Whether the user is an App User", + "type": "boolean", + "example": true + }, + "external_app_user_id": { + "description": "An external identifier for an app user, which can be used to look up\nthe user. This can be used to tie user IDs from external identity\nproviders to Box users.", + "type": "string", + "example": "my-user-1234" + } + } + } + ], + "title": "User (Full)", + "x-box-resource-id": "user--full", + "x-box-variant": "full" + }, + "User--Mini": { + "description": "A mini representation of a user, as can be returned when nested within other\nresources.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "properties": { + "name": { + "description": "The display name of this user", + "type": "string", + "example": "Aaron Levie", + "maxLength": 50, + "nullable": false + }, + "login": { + "description": "The primary email address of this user", + "type": "string", + "format": "email", + "example": "ceo@example.com", + "nullable": false + } + } + } + ], + "title": "User (Mini)", + "x-box-resource-id": "user--mini", + "x-box-variant": "mini" + }, + "UserAvatar": { + "description": "A resource holding URLs to the\navatar uploaded to a Box application.", + "type": "object", + "properties": { + "pic_urls": { + "description": "Represents an object with user avatar URLs.", + "type": "object", + "properties": { + "small": { + "description": "The location of a small-sized avatar.", + "type": "string", + "example": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks! pac3kv01!7B6R5cZLmurEV_xB-KkycPk8Oi7oENUX2O_qUtIuO4342CG IldyCto9hqiQP7uxqYU5V2w63Ft4ln4UVVLDtDZu903OqzkflY2O-Lq00 ubA29xU-RJ6b_KzJEWRYgUhX1zEl3dzWo12g8eWRE2rStf123DF7AYahNqM 1BmLmviL_nODc7SDQHedTXPAjxURUAra5BvtLe7B05AizbNXdPlCNp-LNh _S-eZ_RjDXcGO-MkRWd_3BOMHnvjf450t5BfKoJ15WhEfiMlfXH1tmouHXrsC 66cT6-pzF9E40Iir_zThqSlrFxzP_xcmXzHapr_k-0E2qr2TXp4iC396TSlEw\n" + }, + "large": { + "description": "The location of a large-sized avatar.", + "type": "string", + "example": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks\npac3kv01!lipGQlQQOtCTCoB6zCOArUjVWLFJtLr5tn6aOZMCybhRx0NNuFQbVI36nw\njtEk5YjUUz1KVdVuvU2yDhu_ftK_bvxeKP1Ffrx9vKGVvJ-UJc1z32p6n2CmFzzpc\ngSoX4pnPhFgydAL-u9jDspXUGElr-htDG_HPMiE9DZjqDueOxXHy8xe22wbaPAheC\nao1emv8r_fmufaUgSndeMYmyZj-KqOYsLBrBNgdeiK5tZmPOQggAEUmyQPkrd8W92TQ6sSlIp0r" + }, + "preview": { + "description": "The location of the avatar preview.", + "type": "string", + "example": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks!\npac3kv01!8UcNPweOOAWj2DtHk_dCQB4wJpzyPkl7mT5nHj5ZdjY92ejYCBBZc95--403b29CW\nk-8hSo_uBjh5h9QG42Ihu-cOZ-816sej1kof3SOm5gjn7qjMAx89cHjUaNK-6XasRqSNboenjZ\n04laZuV9vSH12BZGAYycIZvvQ5R66Go8xG5GTMARf2nBU84c4H_SL5iws-HeBS4oQJWOJh6FBl\nsSJDSTI74LGXqeZb3EY_As34VFC95F10uozoTOSubZmPYylPlaKXoKWk2f9wYQso1ZTN7sh-Gc\n9Kp43zMLhArIWhok0Im6FlRAuWOQ03KYgL-k4L5EZp4Gw6B7uqVRwcBbsTwMIorWq1g" + } + } + } + }, + "title": "User avatar", + "x-box-resource-id": "user_avatar", + "x-box-tag": "avatars" + }, + "UserIntegrationMappings": { + "description": "A user representation for integration mappings\nAPI purposes. Fields name and login are not required.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "properties": { + "name": { + "description": "The display name of this user", + "type": "string", + "example": "Aaron Levie", + "maxLength": 50, + "nullable": false + }, + "login": { + "description": "The primary email address of this user", + "type": "string", + "format": "email", + "example": "ceo@example.com", + "nullable": false + } + } + } + ], + "title": "User (Integration Mappings)", + "x-box-resource-id": "user_integration_mappings_reference", + "x-box-tag": "users" + }, + "Users": { + "description": "A list of users.", + "type": "object", + "allOf": [ + { + "type": "object", + "description": "The part of an API response that describes marker\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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "type": "object", + "description": "The part of an API response that describes pagination", + "properties": { + "total_count": { + "description": "One greater than the offset of the last entry in the entire collection.\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", + "example": 5000 + }, + "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", + "example": 1000 + }, + "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", + "example": 2000 + }, + "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", + "example": "type" + }, + "direction": { + "description": "The direction to order by, either ascending or descending", + "type": "string", + "example": "ASC", + "enum": [ + "ASC", + "DESC" + ] + } + } + } + } + } + }, + { + "properties": { + "entries": { + "description": "A list of users", + "type": "array", + "items": { + "$ref": "#/components/schemas/User--Full" + } + } + } + } + ], + "title": "Users", + "x-box-resource-id": "users", + "x-box-tag": "users" + }, + "Watermark": { + "description": "A watermark is a semi-transparent overlay on an embedded file\npreview that displays a viewer's email address or user ID\nand the time of access over a file's content", + "type": "object", + "properties": { + "watermark": { + "type": "object", + "properties": { + "created_at": { + "description": "When this watermark was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When this task was modified", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + } + } + } + }, + "title": "Watermark", + "x-box-resource-id": "watermark", + "x-box-tag": "file_watermarks" + }, + "WebLink": { + "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.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/WebLink--Mini" + }, + { + "properties": { + "parent": { + "allOf": [ + { + "$ref": "#/components/schemas/Folder--Mini" + }, + { + "description": "The parent object the web link belongs to" + } + ] + }, + "description": { + "description": "The description accompanying the web link. This is\nvisible within the Box web application.", + "type": "string", + "example": "Example page" + }, + "path_collection": { + "allOf": [ + { + "title": "Path collection", + "description": "A list of parent folders for an item.", + "type": "object", + "required": [ + "total_count", + "entries" + ], + "properties": { + "total_count": { + "description": "The number of folders in this list.", + "type": "integer", + "format": "int64", + "example": 1, + "nullable": false + }, + "entries": { + "description": "The parent folders for this item", + "type": "array", + "items": { + "$ref": "#/components/schemas/Folder--Mini" + }, + "nullable": false + } + } + }, + { + "description": "The tree of folders that this web link is contained in,\nstarting at the root." + }, + { + "nullable": false + } + ] + }, + "created_at": { + "description": "When this file was created on Box’s servers.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "When this file was last updated on the Box\nservers.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "trashed_at": { + "description": "When this file was moved to the trash.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "purged_at": { + "description": "When this file will be permanently deleted.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00", + "nullable": true + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created this web link" + } + ] + }, + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who last modified this web link" + } + ] + }, + "owned_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who owns this web link" + } + ] + }, + "shared_link": { + "allOf": [ + { + "title": "Shared link", + "description": "Shared links provide direct, read-only access to files or folder on Box.\n\nShared links with open access level allow anyone with the URL\nto access the item, while shared links with company or collaborators access\nlevels can only be accessed by appropriately authenticated Box users.", + "type": "object", + "required": [ + "url", + "accessed", + "effective_access", + "effective_permission", + "is_password_enabled", + "download_count", + "preview_count" + ], + "properties": { + "url": { + "description": "The URL that can be used to access the item on Box.\n\nThis URL will display the item in Box's preview UI where the file\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.", + "type": "string", + "format": "url", + "example": "https://www.box.com/s/vspke7y05sb214wjokpk", + "nullable": false + }, + "download_url": { + "description": "A URL that can be used to download the file. This URL can be used in\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.", + "type": "string", + "format": "url", + "example": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg", + "nullable": true, + "x-box-premium-feature": true + }, + "vanity_url": { + "description": "The \"Custom URL\" that can also be used to preview the item on Box. Custom\nURLs can only be created or modified in the Box Web application.", + "type": "string", + "format": "url", + "example": "https://acme.app.box.com/v/my_url/", + "nullable": true + }, + "vanity_name": { + "description": "The custom name of a shared link, as used in the `vanity_url` field.", + "type": "string", + "example": "my_url", + "nullable": true + }, + "access": { + "description": "The access level for this shared link.\n\n* `open` - provides access to this item to anyone with this link\n* `company` - only provides access to this item to people the same company\n* `collaborators` - only provides access to this item to people who are\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.", + "type": "string", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ], + "nullable": false + }, + "effective_access": { + "description": "The effective access level for the shared link. This can be a more\nrestrictive access level than the value in the `access` field when the\nenterprise settings restrict the allowed access levels.", + "type": "string", + "example": "company", + "enum": [ + "open", + "company", + "collaborators" + ], + "nullable": false + }, + "effective_permission": { + "description": "The effective permissions for this shared link.\nThese result in the more restrictive combination of\nthe share link permissions and the item permissions set\nby the administrator, the owner, and any ancestor item\nsuch as a folder.", + "type": "string", + "example": "can_download", + "enum": [ + "can_edit", + "can_download", + "can_preview", + "no_access" + ], + "nullable": false + }, + "unshared_at": { + "description": "The date and time when this link will be unshared. This field can only be\nset by users with paid accounts.", + "type": "string", + "format": "date-time", + "example": "2018-04-13T13:53:23-07:00", + "nullable": true + }, + "is_password_enabled": { + "description": "Defines if the shared link requires a password to access the item.", + "type": "boolean", + "example": true, + "nullable": false + }, + "permissions": { + "description": "Defines if this link allows a user to preview, edit, and download an item.\nThese permissions refer to the shared link only and\ndo not supersede permissions applied to the item itself.", + "type": "object", + "properties": { + "can_download": { + "description": "Defines if the shared link allows for the item to be downloaded. For\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`.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_preview": { + "description": "Defines if the shared link allows for the item to be previewed.\n\nThis value is always `true`. For shared links on folders this also\napplies to any items in the folder.", + "type": "boolean", + "example": true, + "nullable": false + }, + "can_edit": { + "description": "Defines if the shared link allows for the item to be edited.\n\nThis value can only be `true` if `can_download` is also `true` and if\nthe item has a type of `file`.", + "type": "boolean", + "example": false, + "nullable": false + } + }, + "required": [ + "can_download", + "can_preview", + "can_edit" + ] + }, + "download_count": { + "description": "The number of times this item has been downloaded.", + "type": "integer", + "example": 3, + "nullable": false + }, + "preview_count": { + "description": "The number of times this item has been previewed.", + "type": "integer", + "example": 3, + "nullable": false + } + } + }, + { + "description": "The shared link object for this item. Will be\n`null` if no shared link has been created." + }, + { + "nullable": true + } + ] + }, + "item_status": { + "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", + "type": "string", + "example": "active", + "enum": [ + "active", + "trashed", + "deleted" + ] + } + } + } + ], + "title": "Web link", + "x-box-resource-id": "web_link", + "x-box-variant": "standard" + }, + "WebLink--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.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this web link", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`web_link`", + "type": "string", + "example": "web_link", + "enum": [ + "web_link" + ] + }, + "etag": { + "description": "The entity tag of this web link. Used with `If-Match`\nheaders.", + "type": "string", + "example": "1" + } + }, + "required": [ + "id", + "type" + ], + "title": "Web link (Base)", + "x-box-resource-id": "web_link--base", + "x-box-tag": "web_links", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "mini", + "standard" + ] + }, + "WebLink--Mini": { + "description": "Web links are objects that point to URLs. These objects\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.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/WebLink--Base" + }, + { + "properties": { + "url": { + "description": "The URL this web link points to", + "type": "string", + "example": "https://www.example.com/example/1234" + }, + "sequence_id": { + "allOf": [ + { + "type": "string", + "example": "3", + "nullable": true, + "description": "A numeric identifier that represents the most recent user event\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." + }, + { + "nullable": false + } + ] + }, + "name": { + "description": "The name of the web link", + "type": "string", + "example": "My Bookmark" + } + } + } + ], + "title": "Web link (Mini)", + "x-box-resource-id": "web_link--mini", + "x-box-variant": "mini" + }, + "Webhook": { + "description": "Represents a configured webhook.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Webhook--Mini" + }, + { + "properties": { + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user who created the webhook" + } + ] + }, + "created_at": { + "description": "A timestamp identifying the time that\nthe webhook was created.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "address": { + "description": "The URL that is notified by this webhook", + "type": "string", + "example": "https://example.com/webhooks" + }, + "triggers": { + "description": "An array of event names that this webhook is\nto be triggered for", + "type": "array", + "items": { + "title": "Webhook Trigger", + "example": "FILE.UPLOADED", + "type": "string", + "description": "The event name that triggered this webhook", + "enum": [ + "FILE.UPLOADED", + "FILE.PREVIEWED", + "FILE.DOWNLOADED", + "FILE.TRASHED", + "FILE.DELETED", + "FILE.RESTORED", + "FILE.COPIED", + "FILE.MOVED", + "FILE.LOCKED", + "FILE.UNLOCKED", + "FILE.RENAMED", + "COMMENT.CREATED", + "COMMENT.UPDATED", + "COMMENT.DELETED", + "TASK_ASSIGNMENT.CREATED", + "TASK_ASSIGNMENT.UPDATED", + "METADATA_INSTANCE.CREATED", + "METADATA_INSTANCE.UPDATED", + "METADATA_INSTANCE.DELETED", + "FOLDER.CREATED", + "FOLDER.RENAMED", + "FOLDER.DOWNLOADED", + "FOLDER.RESTORED", + "FOLDER.DELETED", + "FOLDER.COPIED", + "FOLDER.MOVED", + "FOLDER.TRASHED", + "WEBHOOK.DELETED", + "COLLABORATION.CREATED", + "COLLABORATION.ACCEPTED", + "COLLABORATION.REJECTED", + "COLLABORATION.REMOVED", + "COLLABORATION.UPDATED", + "SHARED_LINK.DELETED", + "SHARED_LINK.CREATED", + "SHARED_LINK.UPDATED", + "SIGN_REQUEST.COMPLETED", + "SIGN_REQUEST.DECLINED", + "SIGN_REQUEST.EXPIRED", + "SIGN_REQUEST.SIGNER_EMAIL_BOUNCED" + ] + }, + "example": [ + "FILE.UPLOADED" + ] + } + } + } + ], + "title": "Webhook", + "x-box-resource-id": "webhook", + "x-box-tag": "webhooks", + "x-box-variant": "standard" + }, + "Webhook--Mini": { + "description": "Represents a configured webhook.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this webhook.", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`webhook`", + "type": "string", + "example": "webhook", + "enum": [ + "webhook" + ] + }, + "target": { + "description": "The item that will trigger the webhook", + "type": "object", + "properties": { + "id": { + "description": "The ID of the item to trigger a webhook", + "type": "string", + "example": "1231232" + }, + "type": { + "description": "The type of item to trigger a webhook", + "type": "string", + "example": "file", + "enum": [ + "file", + "folder" + ] + } + } + } + }, + "title": "Webhook (Mini)", + "x-box-resource-id": "webhook--mini", + "x-box-tag": "webhooks", + "x-box-variant": "mini", + "x-box-variants": [ + "mini", + "standard" + ] + }, + "WebhookInvocation": { + "description": "The event that is sent to a webhook address when an event happens.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this webhook invocation", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`webhook_event`", + "type": "string", + "example": "webhook_event", + "enum": [ + "webhook_event" + ] + }, + "webhook": { + "allOf": [ + { + "$ref": "#/components/schemas/Webhook" + }, + { + "description": "The webhook object that triggered this event" + } + ] + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Mini" + }, + { + "description": "The user that triggered this event" + } + ] + }, + "created_at": { + "description": "A timestamp identifying the time that\nthe webhook event was triggered.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "trigger": { + "allOf": [ + { + "title": "Webhook Trigger", + "example": "FILE.UPLOADED", + "type": "string", + "description": "The event name that triggered this webhook", + "enum": [ + "FILE.UPLOADED", + "FILE.PREVIEWED", + "FILE.DOWNLOADED", + "FILE.TRASHED", + "FILE.DELETED", + "FILE.RESTORED", + "FILE.COPIED", + "FILE.MOVED", + "FILE.LOCKED", + "FILE.UNLOCKED", + "FILE.RENAMED", + "COMMENT.CREATED", + "COMMENT.UPDATED", + "COMMENT.DELETED", + "TASK_ASSIGNMENT.CREATED", + "TASK_ASSIGNMENT.UPDATED", + "METADATA_INSTANCE.CREATED", + "METADATA_INSTANCE.UPDATED", + "METADATA_INSTANCE.DELETED", + "FOLDER.CREATED", + "FOLDER.RENAMED", + "FOLDER.DOWNLOADED", + "FOLDER.RESTORED", + "FOLDER.DELETED", + "FOLDER.COPIED", + "FOLDER.MOVED", + "FOLDER.TRASHED", + "WEBHOOK.DELETED", + "COLLABORATION.CREATED", + "COLLABORATION.ACCEPTED", + "COLLABORATION.REJECTED", + "COLLABORATION.REMOVED", + "COLLABORATION.UPDATED", + "SHARED_LINK.DELETED", + "SHARED_LINK.CREATED", + "SHARED_LINK.UPDATED", + "SIGN_REQUEST.COMPLETED", + "SIGN_REQUEST.DECLINED", + "SIGN_REQUEST.EXPIRED", + "SIGN_REQUEST.SIGNER_EMAIL_BOUNCED" + ] + }, + { + "description": "The event name that triggered this webhook" + } + ] + }, + "source": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/File" + }, + { + "$ref": "#/components/schemas/Folder" + } + ] + }, + { + "description": "The item that caused the event to trigger" + } + ] + } + }, + "title": "Webhook (V2) payload", + "x-box-resource-id": "webhook_invocation", + "x-box-tag": "webhooks" + }, + "Webhooks": { + "description": "A list of webhooks.", + "type": "object", + "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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of webhooks", + "type": "array", + "items": { + "$ref": "#/components/schemas/Webhook--Mini" + } + } + } + } + ], + "title": "Webhooks", + "x-box-resource-id": "webhooks", + "x-box-tag": "webhooks" + }, + "Workflow": { + "description": "Box Relay Workflows are objects that represent a named collection of flows.\n\nYour application must be authorized to use the `Manage Box Relay` application\nscope within the developer console in order to use this resource.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Workflow--Mini" + }, + { + "properties": { + "flows": { + "description": "A list of flows assigned to a workflow.", + "type": "array", + "items": { + "type": "object", + "description": "A step in a Box Relay Workflow. Each flow contains a `Trigger` and\na collection of Outcomes to perform once the conditions of a\n`Trigger` are met", + "properties": { + "id": { + "description": "The identifier of the flow", + "type": "string", + "example": "12345" + }, + "type": { + "description": "The flow's resource type", + "type": "string", + "example": "flow", + "enum": [ + "flow" + ] + }, + "trigger": { + "allOf": [ + { + "type": "object", + "properties": { + "type": { + "description": "The trigger's resource type", + "type": "string", + "example": "trigger", + "enum": [ + "trigger" + ] + }, + "trigger_type": { + "description": "The type of trigger selected for this flow", + "type": "string", + "example": "WORKFLOW_MANUAL_START", + "enum": [ + "WORKFLOW_MANUAL_START" + ] + }, + "scope": { + "description": "List of trigger scopes", + "type": "array", + "items": { + "type": "object", + "description": "Object that describes where and how a Trigger condition is met", + "properties": { + "type": { + "description": "The trigger scope's resource type", + "type": "string", + "example": "trigger_scope", + "enum": [ + "trigger_scope" + ] + }, + "ref": { + "description": "Indicates the path of the condition value to check", + "type": "string", + "example": "/event/source/parameters/folder" + }, + "object": { + "description": "The object the `ref` points to", + "type": "object", + "properties": { + "type": { + "description": "The type of the object", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ] + }, + "id": { + "description": "The id of the object", + "type": "string", + "example": "12345" + } + } + } + } + } + } + } + }, + { + "description": "Trigger that initiates flow" + } + ] + }, + "outcomes": { + "allOf": [ + { + "type": "array", + "items": { + "type": "object", + "description": "List of outcomes to perform once the conditions of trigger are met.", + "properties": { + "id": { + "description": "The identifier of the outcome", + "type": "string", + "example": "12345" + }, + "type": { + "description": "The outcomes resource type", + "type": "string", + "example": "outcome", + "enum": [ + "outcome" + ] + }, + "name": { + "description": "The name of the outcome", + "type": "string", + "example": "Task Approval Outcome" + }, + "action_type": { + "allOf": [ + { + "title": "Action Type", + "example": "assign_task", + "type": "string", + "description": "The type of outcome", + "enum": [ + "add_metadata", + "assign_task", + "copy_file", + "copy_folder", + "create_folder", + "delete_file", + "delete_folder", + "lock_file", + "move_file", + "move_folder", + "remove_watermark_file", + "rename_folder", + "restore_folder", + "share_file", + "share_folder", + "unlock_file", + "upload_file", + "wait_for_task", + "watermark_file", + "go_back_to_step", + "apply_file_classification", + "apply_folder_classification", + "send_notification" + ] + }, + { + "description": "The type of outcome" + } + ] + }, + "if_rejected": { + "description": "If `action_type` is `assign_task` and the task is rejected, returns a\nlist of outcomes to complete", + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "description": "The identifier of the outcome", + "type": "string", + "example": "12345" + }, + "type": { + "description": "The outcomes resource type", + "type": "string", + "example": "outcome", + "enum": [ + "outcome" + ] + }, + "name": { + "description": "The name of the outcome", + "type": "string", + "example": "Approval Rejection Outcome" + }, + "action_type": { + "allOf": [ + { + "title": "Action Type", + "example": "assign_task", + "type": "string", + "description": "The type of outcome", + "enum": [ + "add_metadata", + "assign_task", + "copy_file", + "copy_folder", + "create_folder", + "delete_file", + "delete_folder", + "lock_file", + "move_file", + "move_folder", + "remove_watermark_file", + "rename_folder", + "restore_folder", + "share_file", + "share_folder", + "unlock_file", + "upload_file", + "wait_for_task", + "watermark_file", + "go_back_to_step", + "apply_file_classification", + "apply_folder_classification", + "send_notification" + ] + }, + { + "description": "The type of outcome" + } + ] + } + } + } + } + } + } + }, + { + "description": "Actions that are completed once the flow is triggered" + } + ] + }, + "created_at": { + "description": "When this flow was created", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user who created this flow" + } + ] + } + } + } + } + } + } + ], + "title": "Workflow", + "x-box-resource-id": "workflow", + "x-box-variant": "standard" + }, + "Workflow--Full": { + "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.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/Workflow" + }, + { + "properties": { + "created_at": { + "description": "The date and time when the workflow was created on Box", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "modified_at": { + "description": "The date and time when the workflow was last updated on Box", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43-08:00" + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user who created this workflow" + } + ] + }, + "modified_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "The user who last modified this workflow" + } + ] + } + } + } + ], + "title": "Workflow (Full)", + "x-box-resource-id": "workflow--full", + "x-box-variant": "full" + }, + "Workflow--Mini": { + "description": "Box Relay Workflows are objects that represent a named collection of flows.\n\nYou application must be authorized to use the `Manage Box Relay` application\nscope within the developer console in order to use this resource.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for the workflow", + "type": "string", + "example": "11446498" + }, + "type": { + "description": "`workflow`", + "type": "string", + "example": "workflow", + "enum": [ + "workflow" + ] + }, + "name": { + "description": "The name of the workflow", + "type": "string", + "example": "New Hire Workflow" + }, + "description": { + "description": "The description for a workflow.", + "type": "string", + "example": "This workflow sets off a new hire approval flow" + }, + "is_enabled": { + "description": "Specifies if this workflow is enabled", + "type": "boolean", + "example": true + } + }, + "title": "Workflow (Mini)", + "x-box-resource-id": "workflow--mini", + "x-box-tag": "workflows", + "x-box-variant": "mini", + "x-box-variants": [ + "mini", + "standard", + "full" + ] + }, + "Workflows": { + "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.", + "type": "object", + "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", + "example": 1000 + }, + "next_marker": { + "description": "The marker for the start of the next page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", + "nullable": true + }, + "prev_marker": { + "description": "The marker for the start of the previous page of results.", + "type": "string", + "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", + "nullable": true + } + } + }, + { + "properties": { + "entries": { + "description": "A list of workflows", + "type": "array", + "items": { + "$ref": "#/components/schemas/Workflow" + } + } + } + } + ], + "title": "Workflows", + "x-box-resource-id": "workflows", + "x-box-tag": "workflows" + }, + "ZipDownload": { + "description": "Represents a successful request to create a `zip` archive of a list of files\nand folders.", + "type": "object", + "properties": { + "download_url": { + "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 `expires_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.", + "type": "string", + "example": "https://dl.boxcloud.com/2.0/zip_downloads/Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd/content" + }, + "status_url": { + "description": "The URL that can be used to get the status of the `zip` archive being\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`expires_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.", + "type": "string", + "example": "https://api.box.com/2.0/zip_downloads/Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd/status" + }, + "expires_at": { + "description": "The time and date when this archive will expire. After this time the\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.", + "type": "string", + "format": "date-time", + "example": "2019-08-29T23:59:00-07:00" + }, + "name_conflicts": { + "description": "A list of conflicts that occurred when trying to create the archive. This\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.", + "type": "array", + "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": { + "description": "The identifier of the item", + "type": "string", + "example": "12345" + }, + "type": { + "description": "The type of this item", + "type": "string", + "example": "file", + "enum": [ + "file", + "folder" + ] + }, + "original_name": { + "description": "The original name of this item", + "type": "string", + "example": "Report.pdf" + }, + "download_name": { + "description": "The new name of this item as it will appear in the\ndownloaded `zip` archive.", + "type": "string", + "example": "3aa6a7.pdf" + } + } + } + } + } + }, + "example": { + "download_url": "https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content", + "status_url": "https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status", + "expires_at": "2020-07-22T11:26:08Z", + "name_conflicts": [ + [ + { + "id": "12345", + "type": "file", + "original_name": "Report.pdf", + "download_name": "3aa6a7.pdf" + }, + { + "id": "34325", + "type": "file", + "original_name": "Report.pdf", + "download_name": "5d53f2.pdf" + } + ] + ] + }, + "title": "Zip download", + "x-box-reference-category": "zip_downloads", + "x-box-resource-id": "zip_download", + "x-box-tag": "zip_downloads" + }, + "ZipDownloadRequest": { + "description": "A request to create a `zip` archive to download", + "type": "object", + "properties": { + "items": { + "description": "A list of items to add to the `zip` archive. These can\nbe folders or files.", + "type": "array", + "items": { + "type": "object", + "description": "An item to add to the `zip` archive. This can be a file or a folder.", + "required": [ + "type", + "id" + ], + "properties": { + "type": { + "description": "The type of the item to add to the archive.", + "type": "string", + "example": "file", + "enum": [ + "file", + "folder" + ] + }, + "id": { + "description": "The identifier of the item to add to the archive. When this item is\na folder then this can not be the root folder with ID `0`.", + "type": "string", + "example": "12345" + } + } + } + }, + "download_file_name": { + "description": "The optional name of the `zip` archive. This name will be appended by the\n`.zip` file extension, for example `January Financials.zip`.", + "type": "string", + "example": "January Financials" + } + }, + "required": [ + "items" + ], + "title": "Create a `zip` archive" + }, + "ZipDownloadStatus": { + "description": "The status of a `zip` archive being downloaded.", + "type": "object", + "properties": { + "total_file_count": { + "description": "The total number of files in the archive.", + "type": "integer", + "example": 20, + "maximum": 10000, + "minimum": 0 + }, + "downloaded_file_count": { + "description": "The number of files that have already been downloaded.", + "type": "integer", + "example": 10, + "minimum": 0 + }, + "skipped_file_count": { + "description": "The number of files that have been skipped as they could not be\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.", + "type": "integer", + "example": 5, + "minimum": 0 + }, + "skipped_folder_count": { + "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.", + "type": "integer", + "example": 5, + "minimum": 0 + }, + "state": { + "description": "The state of the archive being downloaded.", + "type": "string", + "example": "succeeded", + "default": "in_progress", + "enum": [ + "in_progress", + "failed", + "succeeded" + ] + } + }, + "title": "Zip download status", + "x-box-reference-category": "zip_downloads", + "x-box-resource-id": "zip_download_status", + "x-box-tag": "zip_downloads" + } + }, + "securitySchemes": { + "OAuth2Security": { + "type": "oauth2", + "flows": { + "authorizationCode": { + "authorizationUrl": "https://account.box.com/api/oauth2/authorize", + "tokenUrl": "https://api.box.com/oauth2/token", + "scopes": { + "root_readonly": "Read all files and folders stored in Box", + "root_readwrite": "Read and write all files and folders stored in Box", + "manage_app_users": "Provision and manage app users", + "manage_managed_users": "Provision and manage managed users", + "manage_groups": "Manage an enterprise's groups", + "manage_webhook": "Create webhooks programmatically through the API", + "manage_enterprise_properties": "Manage enterprise properties", + "manage_data_retention": "Manage data retention polices", + "manage_legal_hold": "Manage Legal Holds" + } + } + } + } + } + }, + "security": [ + { + "OAuth2Security": [] + } + ], + "tags": [ + { + "name": "AI", + "description": "A set of endpoints used to\ninteract with supported LLMs.", + "x-box-tag": "ai" + }, + { + "name": "App item associations", + "x-box-tag": "app_item_associations" + }, + { + "name": "Authorization", + "description": "A set of endpoints used to\nmanage user authorization process.", + "x-box-tag": "authorization", + "x-box-priority": true + }, + { + "name": "Box Sign requests", + "description": "Box Sign requests are used\nto submit a file for\nsignature.", + "x-box-tag": "sign_requests" + }, + { + "name": "Classifications", + "description": "Classification labels are\nused for content that is\nsensitive or under security\nrestrictions.", + "x-box-tag": "classifications" + }, + { + "name": "Classifications on files", + "description": "Classification labels are\nused for files that are\nsensitive or under security\nrestrictions.", + "x-box-tag": "file_classifications" + }, + { + "name": "Classifications on folders", + "description": "Classification labels are\nused for folders that are\nsensitive or under security\nrestrictions.", + "x-box-tag": "folder_classifications" + }, + { + "name": "Collaborations", + "description": "Collaborations define access permissions\nfor users and groups to files and folders,\nsimilar to access control lists.", + "x-box-tag": "user_collaborations" + }, + { + "name": "Collaborations (List)", + "description": "A set of endpoints used to\nretrieve file, folder,\npending, and group collaborations.", + "x-box-tag": "list_collaborations" + }, + { + "name": "Collections", + "description": "Collections are a way to group files,\nfolders, and web links without putting them\nall into a folder.", + "x-box-tag": "collections" + }, + { + "name": "Comments", + "description": "Comments are messages generated users on files,\nallowing users to collaborate on a file,\ndiscussing any feedback they might\nhave on the content.", + "x-box-tag": "comments" + }, + { + "name": "Device pinners", + "description": "Device pinners allow enterprises to\ncontrol what devices can use\nnative Box applications.", + "x-box-tag": "device_pinners" + }, + { + "name": "Domain restrictions (User exemptions)", + "description": "A set of endpoints that allow exempting users\nfrom restrictions imposed by the list of\nallowed collaboration domains for a specific enterprise.", + "x-box-tag": "collaboration_allowlist_exempt_targets" + }, + { + "name": "Domain restrictions for collaborations", + "description": "A set of endpoints that manage domains for which users\ncan collaborate with files and folders in an enterprise.", + "x-box-tag": "collaboration_allowlist_entries" + }, + { + "name": "Downloads", + "description": "Downloads allow saving files to the application's server,\nor directly by the end user in a browser.", + "x-box-tag": "downloads" + }, + { + "name": "Email aliases", + "description": "Email aliases provide a list of emails additional\nto the user's primary login email.", + "x-box-tag": "email_aliases" + }, + { + "name": "Events", + "description": "Events provide a way for an\napplication to subscribe to\nany actions performed by\nany user, users, or service in an enterprise.", + "x-box-tag": "events" + }, + { + "name": "File requests", + "description": "File Requests provide a fast and\nsecure way to request files and associated metadata\nfrom anyone.\nUsers can create new file requests\nbased on an existing file request,\nupdate file request settings, activate, deactivate, and delete\nfile requests programmatically.", + "x-box-tag": "file_requests" + }, + { + "name": "File version legal holds", + "description": "A legal hold is a process that an enterprise\ncan use to preserve all forms of potentially relevant\ninformation when\nlitigation is pending or reasonably anticipated.\nA File Version Legal Hold represents all the policies that\nare assigned to a specific file version.", + "x-box-tag": "file_version_legal_holds" + }, + { + "name": "File version retentions", + "description": "A retention policy blocks permanent\ndeletion of content for a specified amount of time.\nA file version retention is a record for a retained file.", + "x-box-tag": "file_version_retentions" + }, + { + "name": "File versions", + "description": "A set of endpoints used to manage specific\nversions of a file.", + "x-box-tag": "file_versions" + }, + { + "name": "Files", + "description": "Files, together with Folders,\nare at the core of the Box API.\nFiles can be uploaded and downloaded,\nas well as hold important metadata\ninformation about the content.", + "x-box-tag": "files" + }, + { + "name": "Folder Locks", + "description": "Folder locks define access restrictions\nplaced by folder owners to prevent\nspecific folders from being moved or deleted.", + "x-box-tag": "folder_locks" + }, + { + "name": "Folders", + "description": "Folders, together with Files,\nare at the core of the Box API.\nFolders can be uploaded and downloaded,\nas well as hold important metadata\ninformation about the content.", + "x-box-tag": "folders" + }, + { + "name": "Integration mappings", + "description": "Integration Mappings allow the users\nto manage where content from partner apps is stored in Box.", + "x-box-tag": "integration_mappings" + }, + { + "name": "Group memberships", + "description": "Group memberships signify that\na user is a part of the group.", + "x-box-tag": "memberships" + }, + { + "name": "Groups", + "description": "Groups created in an enterprise.", + "x-box-tag": "groups" + }, + { + "name": "Invites", + "description": "Invites are used to invite the user to\nan enterprise.", + "x-box-tag": "invites" + }, + { + "name": "Legal hold policies", + "description": "A legal hold is a process that an enterprise\ncan use to preserve all forms of potentially\nrelevant information when litigation is pending or\nreasonably anticipated.", + "x-box-tag": "legal_hold_policies" + }, + { + "name": "Legal hold policy assignments", + "description": "A Legal Hold Policy Assignment\nis a relation between a policy and custodian.\nIn this case, as custodian can be a user, folder,\nfile, or file version.", + "x-box-tag": "legal_hold_policy_assignments" + }, + { + "name": "Metadata cascade policies", + "description": "A metadata cascade policy describes how metadata\ninstances applied to a folder should be applied\nto any item within that folder.", + "x-box-tag": "metadata_cascade_policies" + }, + { + "name": "Metadata instances (Files)", + "description": "A metadata instance describes\nthe relation between a template and a file,\nincluding the values that are assigned for every field.", + "x-box-tag": "file_metadata" + }, + { + "name": "Metadata instances (Folders)", + "description": "A metadata instance describes the relation between a template and a folder,\nincluding the values that are assigned for every field.", + "x-box-tag": "folder_metadata" + }, + { + "name": "Metadata templates", + "description": "A metadata template describes a reusable set\nof key/value pairs that can be assigned to a file.", + "x-box-tag": "metadata_templates" + }, + { + "name": "Recent items", + "description": "Recent items represent items such\nas files or folders that\nthe user accessed recently.", + "x-box-tag": "recent_items" + }, + { + "name": "Retention policies", + "description": "A retention policy blocks permanent deletion of content\nfor a specified amount of time. Admins can create\nretention policies and then assign them to\nspecific folders or their entire enterprise.", + "x-box-tag": "retention_policies" + }, + { + "name": "Retention policy assignments", + "description": "A Retention Policy Assignment is a relation\nbetween a policy and folder or enterprise.\nCreating an assignment puts a retention on\nall the file versions that belong to that folder or enterprise.", + "x-box-tag": "retention_policy_assignments" + }, + { + "name": "Search", + "description": "The Box API provides a way to find content in Box\nusing full-text search queries.", + "x-box-tag": "search" + }, + { + "name": "Session termination", + "description": "Session termination API is used to\nvalidate the roles and permissions of the group,\nand creates asynchronous jobs to terminate the group's sessions.", + "x-box-tag": "session_termination" + }, + { + "name": "Shared links (Files)", + "description": "Files shared links are URLs that are generated for files stored in Box,\nwhich provide direct, read-only access to the resource.", + "x-box-tag": "shared_links_files" + }, + { + "name": "Shared links (Folders)", + "description": "Folders shared links are URLs that are generated for folders stored in Box,\nwhich provide direct, read-only access to the resource.", + "x-box-tag": "shared_links_folders" + }, + { + "name": "Shared links (Web Links)", + "description": "Web links for files are URLs that are generated\nfor web links in Box,\nwhich provide direct, read-only access to the resource.", + "x-box-tag": "shared_links_web_links" + }, + { + "name": "Shield information barriers", + "description": "Shield information barrier in Box defines an ethical wall.\nAn ethical wall is a mechanism that prevents exchanges or communication that\ncould lead to conflicts of interest and therefore result in\nbusiness activities ethically or legally questionable.", + "x-box-tag": "shield_information_barriers" + }, + { + "name": "Shield information barrier segments", + "description": "Shield information barrier segment represents\na defined group of users. A user can be a member\nof only one segment, which makes segments\ndifferent from groups.", + "x-box-tag": "shield_information_barrier_segments" + }, + { + "name": "Shield information barrier segment members", + "description": "Shield information barrier segment member\nrepresents a user that is assigned to a\nspecific segment.", + "x-box-tag": "shield_information_barrier_segment_members" + }, + { + "name": "Shield information barrier reports", + "description": "Shield information barrier reports\ncontain information on what existing collaborations\nwill be removed permanently when the information barrier is enabled.", + "x-box-tag": "shield_information_barrier_reports" + }, + { + "name": "Shield information barrier segment restrictions", + "description": "Shield information barrier segment restriction is\nan access restriction based on the content (file or folder) owner.", + "x-box-tag": "shield_information_barrier_segment_restrictions" + }, + { + "name": "Box Sign templates", + "description": "Sign templates allow you to use a predefined Box Sign\ntemplate when creating a signature request.\nThe template includes placeholders that\nare automatically populated with data when creating the request.", + "x-box-tag": "sign_templates" + }, + { + "name": "Skills", + "description": "Box Skills are designed to allow custom processing\nof files uploaded to Box, with the\nintent of enhancing the underlying metadata of the file.", + "x-box-tag": "skills" + }, + { + "name": "Standard and Zones Storage Policies", + "description": "Storage policy assignment represents the\nstorage zone for items in a given enterprise.", + "x-box-tag": "storage_policies" + }, + { + "name": "Standard and Zones Storage Policy Assignments", + "description": "Storage policy assignment represents the\nrelation between storage zone and the\nassigned item (for example a file stored\nin a specific zone).", + "x-box-tag": "storage_policy_assignments" + }, + { + "name": "Task assignments", + "description": "A task assignment defines which\ntask is assigned to which user to complete.", + "x-box-tag": "task_assignments" + }, + { + "name": "Tasks", + "description": "Tasks allow users to request collaborators on a file\nto review a file or complete a piece of work.\nTasks can be used by developers to create file-centric workflows.", + "x-box-tag": "tasks" + }, + { + "name": "Terms of service", + "description": "A set of endpoints used to\nmanage terms of service agreements.", + "x-box-tag": "terms_of_services" + }, + { + "name": "Terms of service user statuses", + "description": "A set of endpoints used to\nmanage the status of terms of service\nfor a particular user.", + "x-box-tag": "terms_of_service_user_statuses" + }, + { + "name": "Transfer folders", + "description": "API designed to move all of the items\n(files, folders and workflows)\nowned by a user into another user's account.", + "x-box-tag": "transfer" + }, + { + "name": "Trashed files", + "description": "Files that were deleted and\nare in trash.", + "x-box-tag": "trashed_files" + }, + { + "name": "Trashed folders", + "description": "Folders that were deleted and\nare in trash.", + "x-box-tag": "trashed_folders" + }, + { + "name": "Trashed items", + "description": "Items that were deleted and\nare in trash.", + "x-box-tag": "trashed_items" + }, + { + "name": "Trashed web links", + "description": "Web links that were deleted and\nare in trash.", + "x-box-tag": "trashed_web_links" + }, + { + "name": "Uploads", + "description": "The direct file upload API supports files\nup to 50MB in size and sends all\nthe binary data to the Box API in 1 API request.", + "x-box-tag": "uploads" + }, + { + "name": "Uploads (Chunked)", + "description": "The chunked upload endpoints support files from\n20MB in size and allow an application\nto upload the file in parts,\nallowing for more control to catch any errors\nand retry parts individually.", + "x-box-tag": "chunked_uploads" + }, + { + "name": "User avatars", + "description": "User avatars are JPG or PNG files\nuploaded to Box to represent the\nuser image. They are then displayed\nin the user account.", + "x-box-tag": "avatars" + }, + { + "name": "Users", + "description": "Box API supports a variety of users,\nranging from real employees\nlogging in with their Managed User account,\nto applications using App Users to drive powerful\nautomation workflows.", + "x-box-tag": "users" + }, + { + "name": "Watermarks (Files)", + "description": "A watermark is a semi-transparent\noverlay on an embedded file\npreview that displays a viewer's email address\nor user ID and the time of access over\nthe file.", + "x-box-tag": "file_watermarks" + }, + { + "name": "Watermarks (Folders)", + "description": "A watermark is a semi-transparent overlay on an embedded folder\npreview that displays a viewer's email address or user ID\nand the time of access over\nthe folder content.", + "x-box-tag": "folder_watermarks" + }, + { + "name": "Web links", + "description": "Web links are objects that point to URLs.\nThese objects are also known as bookmarks\nwithin the Box web application.", + "x-box-tag": "web_links" + }, + { + "name": "Webhooks", + "description": "Webhooks allow you to monitor Box content for events,\nand receive notifications to a URL of your choice when they occur.\nFor example, a workflow may include waiting\nfor a file to be downloaded to delete a shared link.", + "x-box-tag": "webhooks" + }, + { + "name": "Workflows", + "description": "Box Relay Workflows are objects that represent\na named collection of flows.", + "x-box-tag": "workflows" + }, + { + "name": "Zip Downloads", + "description": "Zip downloads represent a successful request\nto create a ZIP archive with files and folders.", + "x-box-tag": "zip_downloads" + } + ], + "externalDocs": { + "description": "Box Developer Documentation", + "url": "https://developer.box.com" + } +} \ No newline at end of file