From 63e033b2362cbb45ff8eca41c766216636378fdc Mon Sep 17 00:00:00 2001
From: box-apimgmt <apimgmt@box.com>
Date: Tue, 30 Apr 2024 03:44:08 -0700
Subject: [PATCH] feat: update openapi specification

---
 openapi.json | 314 +++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 282 insertions(+), 32 deletions(-)

diff --git a/openapi.json b/openapi.json
index 27648081..78ef42a1 100644
--- a/openapi.json
+++ b/openapi.json
@@ -14,7 +14,7 @@
       "url": "http://www.apache.org/licenses/LICENSE-2.0"
     },
     "version": "2.0.0",
-    "x-box-commit-hash": "a2f6edcf0a"
+    "x-box-commit-hash": "db940e79a7"
   },
   "servers": [
     {
@@ -301,7 +301,6 @@
           "Files"
         ],
         "x-box-tag": "files",
-        "x-box-enable-explorer": true,
         "description": "Retrieves the details about a file.",
         "parameters": [
           {
@@ -562,7 +561,6 @@
           "Files"
         ],
         "x-box-tag": "files",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Updates a file. This can be used to rename or move a file,\ncreate a shared link, or lock a file.",
         "parameters": [
@@ -2052,7 +2050,6 @@
           "Files"
         ],
         "x-box-tag": "files",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "parameters": [
           {
@@ -3622,6 +3619,7 @@
         ],
         "x-box-tag": "file_metadata",
         "x-box-sanitized": true,
+        "x-box-enable-explorer": false,
         "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": [
           {
@@ -4468,7 +4466,6 @@
           "File requests"
         ],
         "x-box-tag": "file_requests",
-        "x-box-enable-explorer": true,
         "description": "Retrieves the information about a file request.",
         "parameters": [
           {
@@ -4542,7 +4539,6 @@
           "File requests"
         ],
         "x-box-tag": "file_requests",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Updates a file request. This can be used to activate or\ndeactivate a file request.",
         "parameters": [
@@ -4725,7 +4721,6 @@
           "File requests"
         ],
         "x-box-tag": "file_requests",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Copies an existing file request that is already present on one folder,\nand applies it to another folder.",
         "parameters": [
@@ -4821,7 +4816,6 @@
           "Folders"
         ],
         "x-box-tag": "folders",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "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": [
@@ -5120,7 +5114,6 @@
         ],
         "x-box-tag": "folders",
         "x-box-sanitized": true,
-        "x-box-enable-explorer": true,
         "parameters": [
           {
             "name": "folder_id",
@@ -5539,7 +5532,6 @@
         ],
         "x-box-tag": "folders",
         "x-box-sanitized": true,
-        "x-box-enable-explorer": true,
         "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": [
           {
@@ -5718,7 +5710,6 @@
           "Folders"
         ],
         "x-box-tag": "folders",
-        "x-box-enable-explorer": true,
         "description": "Creates a new empty folder within the specified parent folder.",
         "parameters": [
           {
@@ -5879,7 +5870,6 @@
       "post": {
         "operationId": "post_folders_id_copy",
         "summary": "Copy folder",
-        "x-box-enable-explorer": true,
         "x-box-tag": "folders",
         "description": "Creates a copy of a folder within a destination folder.\n\nThe original folder will not be changed.",
         "tags": [
@@ -7411,7 +7401,6 @@
         ],
         "x-box-tag": "folder_locks",
         "x-box-sanitized": true,
-        "x-box-enable-explorer": true,
         "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": [
           {
@@ -9324,7 +9313,6 @@
         ],
         "x-box-tag": "search",
         "x-box-sanitized": true,
-        "x-box-enable-explorer": true,
         "description": "Create a search using SQL-like syntax to return items that match specific\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": {
@@ -9562,6 +9550,7 @@
           "Comments"
         ],
         "x-box-tag": "comments",
+        "x-box-enable-explorer": false,
         "summary": "Create comment",
         "description": "Adds a comment by the user to a specific file, or\nas a reply to an other comment.",
         "parameters": [
@@ -10132,7 +10121,6 @@
           "Search"
         ],
         "x-box-tag": "search",
-        "x-box-enable-explorer": true,
         "description": "Searches for files, folders, web links, and shared files across the\nusers content or across the entire enterprise.",
         "parameters": [
           {
@@ -11283,7 +11271,6 @@
           "Shared links (Files)"
         ],
         "x-box-tag": "shared_links_files",
-        "x-box-enable-explorer": true,
         "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": [
           {
@@ -11360,7 +11347,6 @@
           "Shared links (Files)"
         ],
         "x-box-tag": "shared_links_files",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Gets the information for a shared link on a file.",
         "parameters": [
@@ -11474,7 +11460,6 @@
           "Shared links (Files)"
         ],
         "x-box-tag": "shared_links_files",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Adds a shared link to a file.",
         "parameters": [
@@ -11682,7 +11667,6 @@
           "Shared links (Files)"
         ],
         "x-box-tag": "shared_links_files",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Updates a shared link on a file.",
         "parameters": [
@@ -11890,7 +11874,6 @@
           "Shared links (Files)"
         ],
         "x-box-tag": "shared_links_files",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Removes a shared link from a file.",
         "parameters": [
@@ -12024,7 +12007,6 @@
           "Shared links (Folders)"
         ],
         "x-box-tag": "shared_links_folders",
-        "x-box-enable-explorer": true,
         "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": [
           {
@@ -12101,7 +12083,6 @@
           "Shared links (Folders)"
         ],
         "x-box-tag": "shared_links_folders",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Gets the information for a shared link on a folder.",
         "parameters": [
@@ -12216,7 +12197,6 @@
           "Shared links (Folders)"
         ],
         "x-box-tag": "shared_links_folders",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Adds a shared link to a folder.",
         "parameters": [
@@ -12425,7 +12405,6 @@
           "Shared links (Folders)"
         ],
         "x-box-tag": "shared_links_folders",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Updates a shared link on a folder.",
         "parameters": [
@@ -12634,7 +12613,6 @@
           "Shared links (Folders)"
         ],
         "x-box-tag": "shared_links_folders",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Removes a shared link from a folder.",
         "parameters": [
@@ -13301,7 +13279,6 @@
           "Shared links (Web Links)"
         ],
         "x-box-tag": "shared_links_web_links",
-        "x-box-enable-explorer": true,
         "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": [
           {
@@ -13378,7 +13355,6 @@
           "Shared links (Web Links)"
         ],
         "x-box-tag": "shared_links_web_links",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Gets the information for a shared link on a web link.",
         "parameters": [
@@ -13492,7 +13468,6 @@
           "Shared links (Web Links)"
         ],
         "x-box-tag": "shared_links_web_links",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Adds a shared link to a web link.",
         "parameters": [
@@ -13700,7 +13675,6 @@
           "Shared links (Web Links)"
         ],
         "x-box-tag": "shared_links_web_links",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Updates a shared link on a web link.",
         "parameters": [
@@ -13908,7 +13882,6 @@
           "Shared links (Web Links)"
         ],
         "x-box-tag": "shared_links_web_links",
-        "x-box-enable-explorer": true,
         "x-box-sanitized": true,
         "description": "Removes a shared link from a web link.",
         "parameters": [
@@ -14591,7 +14564,6 @@
           "Users"
         ],
         "x-box-tag": "users",
-        "x-box-enable-explorer": true,
         "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": [
           {
@@ -17688,7 +17660,6 @@
         ],
         "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.",
         "x-box-tag": "recent_items",
-        "x-box-enable-explorer": true,
         "parameters": [
           {
             "name": "fields",
@@ -23908,6 +23879,110 @@
           }
         }
       }
+    },
+    "/v2/ai/ask": {
+      "post": {
+        "operationId": "post_ai_ask",
+        "summary": "Send AI Ask request",
+        "tags": [
+          "AI"
+        ],
+        "x-box-tag": "ai",
+        "description": "Sends an AI request to supported LLMs and returns an answer specifically focused on the user's question given the provided context.",
+        "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"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "An unexpected client error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ClientError"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "An unexpected server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ClientError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v2/ai/text_gen": {
+      "post": {
+        "operationId": "post_ai_text_gen",
+        "summary": "Send AI Text Gen request",
+        "tags": [
+          "AI"
+        ],
+        "x-box-tag": "ai",
+        "description": "Sends an AI request to supported LLMs and returns an answer specifically focused on the creation of new text.",
+        "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"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "An unexpected client error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ClientError"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "An unexpected server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ClientError"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {
@@ -23934,6 +24009,147 @@
       }
     },
     "schemas": {
+      "AiAsk": {
+        "title": "AI Ask Request",
+        "type": "object",
+        "x-box-tag": "ai",
+        "required": [
+          "mode",
+          "prompt",
+          "items"
+        ],
+        "properties": {
+          "mode": {
+            "type": "string",
+            "description": "The mode specifies if this request is for a single or multiple items.",
+            "enum": [
+              "multiple_item_qa",
+              "single_item_qa"
+            ],
+            "example": "multiple_item_qa",
+            "nullable": false
+          },
+          "prompt": {
+            "type": "string",
+            "description": "The prompt provided by the client to be answered by the LLM.",
+            "example": "What is the value provided by public APIs based on this document?"
+          },
+          "items": {
+            "type": "array",
+            "description": "The items to be processed by the LLM, often files.",
+            "minItems": 1,
+            "maxItems": 25,
+            "uniqueItems": true,
+            "items": {
+              "type": "object",
+              "description": "The item to be processed by the LLM.",
+              "required": [
+                "id",
+                "type"
+              ],
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "description": "The id of the item",
+                  "example": "123"
+                },
+                "type": {
+                  "type": "string",
+                  "description": "The type of the item",
+                  "enum": [
+                    "file"
+                  ],
+                  "example": "file"
+                },
+                "content": {
+                  "type": "string",
+                  "description": "The content of the item, often the text representation.",
+                  "example": "This is file content."
+                }
+              }
+            }
+          }
+        },
+        "description": "AI Ask request object"
+      },
+      "AiTextGen": {
+        "title": "AI Text Gen Request",
+        "type": "object",
+        "x-box-tag": "ai",
+        "required": [
+          "prompt",
+          "items"
+        ],
+        "properties": {
+          "prompt": {
+            "type": "string",
+            "description": "The prompt provided by the client to be answered by the LLM.",
+            "example": "Write an email to a client about the importance of public APIs."
+          },
+          "items": {
+            "type": "array",
+            "description": "The items to be processed by the LLM, often files.",
+            "required": [
+              "id",
+              "type"
+            ],
+            "minItems": 1,
+            "maxItems": 1,
+            "uniqueItems": true,
+            "items": {
+              "type": "object",
+              "description": "The item to be processed by the LLM.",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "description": "The id of the item.",
+                  "example": "123"
+                },
+                "type": {
+                  "type": "string",
+                  "description": "The type of the item.",
+                  "enum": [
+                    "file"
+                  ],
+                  "example": "file"
+                },
+                "content": {
+                  "type": "string",
+                  "description": "The content to use as context for generating new text or editing existing text.",
+                  "example": "This is file content."
+                }
+              }
+            }
+          },
+          "dialogue_history": {
+            "type": "array",
+            "description": "The history of prompts and answers previously passed to the LLM. This provides additional context to the LLM in generating the response.",
+            "items": {
+              "type": "object",
+              "description": "A context object that can hold prior prompts and answers.",
+              "properties": {
+                "prompt": {
+                  "type": "string",
+                  "description": "The prompt previously provided by the client and answered by the LLM.",
+                  "example": "Make my email about public APIs sound more professional."
+                },
+                "answer": {
+                  "type": "string",
+                  "description": "The answer previously provided by the LLM.",
+                  "example": "Here is the first draft of your professional email about public APIs."
+                },
+                "created_at": {
+                  "type": "string",
+                  "format": "date-time",
+                  "description": "The ISO date formatted timestamp of when the previous answer to the prompt was created.",
+                  "example": "2012-12-12T10:53:43-08:00"
+                }
+              }
+            }
+          }
+        },
+        "description": "AI Text Gen Request object"
+      },
       "PostOAuth2Token": {
         "title": "Token request",
         "type": "object",
@@ -24942,6 +25158,35 @@
           }
         }
       },
+      "AiResponse": {
+        "title": "AI Response",
+        "type": "object",
+        "x-box-resource-id": "ai_response",
+        "x-box-tag": "ai",
+        "required": [
+          "answer",
+          "created_at"
+        ],
+        "properties": {
+          "answer": {
+            "type": "string",
+            "description": "The answer provided by the LLM.",
+            "example": "Public APIs are important because of key and important reasons."
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "The ISO date formatted timestamp of when the answer to the prompt was created.",
+            "example": "2012-12-12T10:53:43-08:00"
+          },
+          "completion_reason": {
+            "type": "string",
+            "description": "The reason the response finishes.",
+            "example": "done"
+          }
+        },
+        "description": "AI response"
+      },
       "Classification": {
         "title": "Classification",
         "type": "object",
@@ -37989,6 +38234,11 @@
     }
   ],
   "tags": [
+    {
+      "name": "AI",
+      "description": "A set of endpoints used to\ninteract with supported LLMs.",
+      "x-box-tag": "ai"
+    },
     {
       "name": "Authorization",
       "description": "A set of endpoints used to\nmanage user authorization process.",