diff --git a/openapi.json b/openapi.json index 2aa5c8cf..4bcf333c 100644 --- a/openapi.json +++ b/openapi.json @@ -14,7 +14,7 @@ "url": "http://www.apache.org/licenses/LICENSE-2.0" }, "version": "2024.0", - "x-box-commit-hash": "eff357f39b" + "x-box-commit-hash": "f40de715da" }, "servers": [ { diff --git a/openapi/openapi-v2025.0.json b/openapi/openapi-v2025.0.json index bf67badd..495c9af9 100644 --- a/openapi/openapi-v2025.0.json +++ b/openapi/openapi-v2025.0.json @@ -14,7 +14,7 @@ "url": "http://www.apache.org/licenses/LICENSE-2.0" }, "version": "2025.0", - "x-box-commit-hash": "eff357f39b" + "x-box-commit-hash": "f40de715da" }, "servers": [ { @@ -913,65 +913,193 @@ ] } }, - "/shield_lists": { + "/hubs": { "get": { - "operationId": "get_shield_lists_v2025.0", - "summary": "Get all shield lists in enterprise", - "description": "Retrieves all shield lists in the enterprise.", + "operationId": "get_hubs_v2025.0", + "summary": "List all hubs", + "description": "Retrieves all hubs for requesting user.", + "x-stability-level": "beta", "parameters": [ + { + "name": "query", + "in": "query", + "description": "The query string to search for hubs.", + "required": false, + "schema": { + "type": "string" + }, + "example": "Box" + }, + { + "name": "scope", + "in": "query", + "description": "The scope of the hubs to retrieve. Possible values include `editable`,\n`view_only`, and `all`. Default is `all`.", + "required": false, + "schema": { + "type": "string", + "default": "all" + }, + "example": "all" + }, + { + "name": "sort", + "in": "query", + "description": "The field to sort results by. \nPossible values include `name`, `updated_at`,\n`last_accessed_at`, `view_count`, and `relevance`.\nDefault is `relevance`.", + "required": false, + "schema": { + "type": "string", + "default": "relevance" + }, + "example": "name" + }, + { + "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": "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 + }, { "$ref": "#/components/parameters/BoxVersionHeader" } ], "responses": { "200": { - "description": "Returns the list of shield list objects.", + "description": "Returns all hubs for the given user or enterprise.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ShieldLists" + "$ref": "#/components/schemas/Hubs" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" } } } } }, - "x-box-tag": "shield_lists", + "x-box-tag": "hubs", "tags": [ - "Shield lists" + "Hubs" ] - }, - "post": { - "operationId": "post_shield_lists_v2025.0", - "summary": "Create shield list", - "description": "Creates a shield list.", + } + }, + "/enterprise_hubs": { + "get": { + "operationId": "get_enterprise_hubs_v2025.0", + "summary": "List all hubs for requesting enterprise", + "description": "Retrieves all hubs for a given enterprise.\n\nAdmins or Hub Co-admins of an enterprise\nwith GCM scope can make this call.", "parameters": [ + { + "name": "query", + "in": "query", + "description": "The query string to search for hubs.", + "required": false, + "schema": { + "type": "string" + }, + "example": "Box" + }, + { + "name": "sort", + "in": "query", + "description": "The field to sort results by. \nPossible values include `name`, `updated_at`,\n`last_accessed_at`, `view_count`, and `relevance`.\nDefault is `relevance`.", + "required": false, + "schema": { + "type": "string", + "default": "relevance" + }, + "example": "name" + }, + { + "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": "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 + }, { "$ref": "#/components/parameters/BoxVersionHeader" } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ShieldListsCreate" - } - } - } - }, "responses": { "200": { - "description": "Returns the shield list object.", + "description": "Returns all hubs for the given user or enterprise.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ShieldList" + "$ref": "#/components/schemas/Hubs" } } } }, - "409": { - "description": "The shield list with this name already exists.", + "default": { + "description": "An unexpected client error.", "content": { "application/json": { "schema": { @@ -981,45 +1109,46 @@ } } }, - "x-box-tag": "shield_lists", + "x-box-tag": "hubs", "tags": [ - "Shield lists" - ] + "Hubs" + ], + "x-box-stability": "beta" } }, - "/shield_lists/{shield_list_id}": { + "/hubs/{hub_id}": { "get": { - "operationId": "get_shield_lists_id_v2025.0", - "summary": "Get single shield list by shield list id", - "description": "Retrieves a single shield list by its ID.", + "operationId": "get_hubs_id_v2025.0", + "summary": "Get hub information by ID", + "description": "Retrieves details for a hub by its ID.", "parameters": [ { - "$ref": "#/components/parameters/BoxVersionHeader" - }, - { - "name": "shield_list_id", + "name": "hub_id", "in": "path", - "description": "The unique identifier that represents a shield list.\nThe ID for any Shield List can be determined by the response from the endpoint\nfetching all shield lists for the enterprise.", + "description": "The unique identifier that represent a hub.\n\nThe ID for any hub can be determined\nby visiting this hub in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/hubs/123`\nthe `hub_id` is `123`.", "required": true, "schema": { "type": "string" }, - "example": "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " + "example": "12345" + }, + { + "$ref": "#/components/parameters/BoxVersionHeader" } ], "responses": { "200": { - "description": "Returns the shield list object.", + "description": "Returns a hub object.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ShieldList" + "$ref": "#/components/schemas/Hub" } } } }, - "404": { - "description": "The shield list was not found.", + "401": { + "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { @@ -1027,38 +1156,9 @@ } } } - } - }, - "x-box-tag": "shield_lists", - "tags": [ - "Shield lists" - ] - }, - "delete": { - "operationId": "delete_shield_lists_id_v2025.0", - "summary": "Delete single shield list by shield list id", - "description": "Delete a single shield list by its ID.", - "parameters": [ - { - "$ref": "#/components/parameters/BoxVersionHeader" - }, - { - "name": "shield_list_id", - "in": "path", - "description": "The unique identifier that represents a shield list.\nThe ID for any Shield List can be determined by the response from the endpoint\nfetching all shield lists for the enterprise.", - "required": true, - "schema": { - "type": "string" - }, - "example": "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " - } - ], - "responses": { - "204": { - "description": "Shield List correctly removed. No content in response." }, - "400": { - "description": "The shield list is assigned to some rules and cannot be removed.", + "404": { + "description": "Returned if the hub is not found, or the user does not\nhave access to the hub.", "content": { "application/json": { "schema": { @@ -1067,8 +1167,8 @@ } } }, - "404": { - "description": "The shield list was not found.", + "default": { + "description": "An unexpected client error.", "content": { "application/json": { "schema": { @@ -1078,52 +1178,47 @@ } } }, - "x-box-tag": "shield_lists", + "x-box-tag": "hubs", "tags": [ - "Shield lists" - ] + "Hubs" + ], + "x-box-stability": "beta" }, - "put": { - "operationId": "put_shield_lists_id_v2025.0", - "summary": "Update shield list", - "description": "Updates a shield list.", + "delete": { + "operationId": "delete_hubs_id_v2025.0", + "summary": "Delete hub", + "description": "Deletes a single hub.", "parameters": [ { - "$ref": "#/components/parameters/BoxVersionHeader" - }, - { - "name": "shield_list_id", + "name": "hub_id", "in": "path", - "description": "The unique identifier that represents a shield list.\nThe ID for any Shield List can be determined by the response from the endpoint\nfetching all shield lists for the enterprise.", + "description": "The unique identifier that represent a hub.\n\nThe ID for any hub can be determined\nby visiting this hub in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/hubs/123`\nthe `hub_id` is `123`.", "required": true, "schema": { "type": "string" }, - "example": "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " + "example": "12345" + }, + { + "$ref": "#/components/parameters/BoxVersionHeader" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ShieldListsUpdate" - } - } - } - }, "responses": { - "200": { - "description": "Returns the shield list object.", + "204": { + "description": "A blank response is returned if the hub was\nsuccessfully deleted." + }, + "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/ShieldList" + "$ref": "#/components/schemas/ClientError" } } } }, "404": { - "description": "The shield list was not found.", + "description": "Returned if the hub is not found or has already been deleted, or the user\ndoes not have access to the hub.", "content": { "application/json": { "schema": { @@ -1132,8 +1227,8 @@ } } }, - "409": { - "description": "The shield list with this name already exists.", + "default": { + "description": "An unexpected client error.", "content": { "application/json": { "schema": { @@ -1143,122 +1238,1418 @@ } } }, - "x-box-tag": "shield_lists", + "x-box-tag": "hubs", "tags": [ - "Shield lists" - ] - } - } - }, - "components": { - "parameters": { - "BoxVersionHeader": { - "name": "box-version", - "in": "header", - "description": "Version header.", - "allowEmptyValue": false, - "required": true, - "schema": { - "type": "string", - "enum": [ - "2025.0" - ] - }, - "example": "2025.0" + "Hubs" + ], + "x-box-stability": "beta" } }, - "schemas": { - "ClientError": { + "/hub_collaborations": { + "get": { + "operationId": "get_hub_collaborations_v2025.0", + "summary": "Get hub collaborations", + "description": "Retrieves all collaborations for a hub.", + "parameters": [ + { + "name": "hub_id", + "in": "query", + "description": "The unique identifier that represent a hub.\n\nThe ID for any hub can be determined\nby visiting this hub in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/hubs/123`\nthe `hub_id` is `123`.", + "required": true, + "schema": { + "type": "string" + }, + "example": "12345" + }, + { + "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 + }, + { + "$ref": "#/components/parameters/BoxVersionHeader" + } + ], + "responses": { + "200": { + "description": "Retrieves the collaborations associated with the specified hub.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HubCollaborations" + } + } + } + }, + "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 hub is not found, or the user does not\nhave access to the hub.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "hub_collaborations", + "tags": [ + "Hub Collaborations" + ], + "x-box-stability": "beta" + }, + "post": { + "operationId": "post_hub_collaborations_v2025.0", + "summary": "Create hub collaboration", + "description": "Adds a collaboration for a single user or a single group to a hub.\n\nCollaborations can be created using email address, user IDs, or group IDs.", + "parameters": [ + { + "$ref": "#/components/parameters/BoxVersionHeader" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HubCollaborationCreateRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Returns a new hub collaboration object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HubCollaboration" + } + } + } + }, + "403": { + "description": "Returns an error when the user does not have the\nright permissions to create the collaboration.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "hub_collaborations", + "tags": [ + "Hub Collaborations" + ], + "x-box-stability": "beta" + } + }, + "/hub_collaborations/{hub_collaboration_id}": { + "get": { + "operationId": "get_hub_collaborations_id_v2025.0", + "summary": "Get hub collaboration by collaboration ID", + "description": "Retrieves details for a hub collaboration by collaboration ID.", + "parameters": [ + { + "name": "hub_collaboration_id", + "in": "path", + "description": "The ID of the hub collaboration.", + "required": true, + "schema": { + "type": "string" + }, + "example": "1234" + }, + { + "$ref": "#/components/parameters/BoxVersionHeader" + } + ], + "responses": { + "200": { + "description": "Returns a hub collaboration object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HubCollaboration" + } + } + } + }, + "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 hub is not found, or the user does not\nhave access to the hub.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "hub_collaborations", + "tags": [ + "Hub Collaborations" + ], + "x-box-stability": "beta" + }, + "put": { + "operationId": "put_hub_collaborations_id_v2025.0", + "summary": "Update hub collaboration", + "description": "Updates a hub collaboration.\nCan be used to change the hub role.", + "parameters": [ + { + "name": "hub_collaboration_id", + "in": "path", + "description": "The ID of the hub collaboration.", + "required": true, + "schema": { + "type": "string" + }, + "example": "1234" + }, + { + "$ref": "#/components/parameters/BoxVersionHeader" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HubCollaborationUpdateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Returns an updated hub collaboration object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HubCollaboration" + } + } + } + }, + "403": { + "description": "Returns an error if the authenticated user does not have the right\npermissions to update the collaboration.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "hub_collaborations", + "tags": [ + "Hub Collaborations" + ], + "x-box-stability": "beta" + }, + "delete": { + "operationId": "delete_hub_collaborations_id_v2025.0", + "summary": "Remove hub collaboration", + "description": "Deletes a single hub collaboration.", + "parameters": [ + { + "name": "hub_collaboration_id", + "in": "path", + "description": "The ID of the hub collaboration.", + "required": true, + "schema": { + "type": "string" + }, + "example": "1234" + }, + { + "$ref": "#/components/parameters/BoxVersionHeader" + } + ], + "responses": { + "204": { + "description": "A blank response is returned if the hub collaboration was\nsuccessfully deleted." + }, + "404": { + "description": "Returns an error if the hub collaboration could not be found,\nor the authenticated user does not have access to the hub collaboration.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "hub_collaborations", + "tags": [ + "Hub Collaborations" + ], + "x-box-stability": "beta" + } + }, + "/shield_lists": { + "get": { + "operationId": "get_shield_lists_v2025.0", + "summary": "Get all shield lists in enterprise", + "description": "Retrieves all shield lists in the enterprise.", + "parameters": [ + { + "$ref": "#/components/parameters/BoxVersionHeader" + } + ], + "responses": { + "200": { + "description": "Returns the list of shield list objects.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldLists" + } + } + } + } + }, + "x-box-tag": "shield_lists", + "tags": [ + "Shield lists" + ] + }, + "post": { + "operationId": "post_shield_lists_v2025.0", + "summary": "Create shield list", + "description": "Creates a shield list.", + "parameters": [ + { + "$ref": "#/components/parameters/BoxVersionHeader" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldListsCreate" + } + } + } + }, + "responses": { + "200": { + "description": "Returns the shield list object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldList" + } + } + } + }, + "409": { + "description": "The shield list with this name already exists.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_lists", + "tags": [ + "Shield lists" + ] + } + }, + "/shield_lists/{shield_list_id}": { + "get": { + "operationId": "get_shield_lists_id_v2025.0", + "summary": "Get single shield list by shield list id", + "description": "Retrieves a single shield list by its ID.", + "parameters": [ + { + "$ref": "#/components/parameters/BoxVersionHeader" + }, + { + "name": "shield_list_id", + "in": "path", + "description": "The unique identifier that represents a shield list.\nThe ID for any Shield List can be determined by the response from the endpoint\nfetching all shield lists for the enterprise.", + "required": true, + "schema": { + "type": "string" + }, + "example": "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " + } + ], + "responses": { + "200": { + "description": "Returns the shield list object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldList" + } + } + } + }, + "404": { + "description": "The shield list was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_lists", + "tags": [ + "Shield lists" + ] + }, + "delete": { + "operationId": "delete_shield_lists_id_v2025.0", + "summary": "Delete single shield list by shield list id", + "description": "Delete a single shield list by its ID.", + "parameters": [ + { + "$ref": "#/components/parameters/BoxVersionHeader" + }, + { + "name": "shield_list_id", + "in": "path", + "description": "The unique identifier that represents a shield list.\nThe ID for any Shield List can be determined by the response from the endpoint\nfetching all shield lists for the enterprise.", + "required": true, + "schema": { + "type": "string" + }, + "example": "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " + } + ], + "responses": { + "204": { + "description": "Shield List correctly removed. No content in response." + }, + "400": { + "description": "The shield list is assigned to some rules and cannot be removed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "The shield list was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_lists", + "tags": [ + "Shield lists" + ] + }, + "put": { + "operationId": "put_shield_lists_id_v2025.0", + "summary": "Update shield list", + "description": "Updates a shield list.", + "parameters": [ + { + "$ref": "#/components/parameters/BoxVersionHeader" + }, + { + "name": "shield_list_id", + "in": "path", + "description": "The unique identifier that represents a shield list.\nThe ID for any Shield List can be determined by the response from the endpoint\nfetching all shield lists for the enterprise.", + "required": true, + "schema": { + "type": "string" + }, + "example": "90fb0e17-c332-40ed-b4f9-fa8908fbbb24 " + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldListsUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "Returns the shield list object.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ShieldList" + } + } + } + }, + "404": { + "description": "The shield list was not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "409": { + "description": "The shield list with this name already exists.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "shield_lists", + "tags": [ + "Shield lists" + ] + } + } + }, + "components": { + "parameters": { + "BoxVersionHeader": { + "name": "box-version", + "in": "header", + "description": "Version header.", + "allowEmptyValue": false, + "required": true, + "schema": { + "type": "string", + "enum": [ + "2025.0" + ] + }, + "example": "2025.0" + } + }, + "schemas": { + "ClientError": { "description": "A generic error.", "type": "object", "properties": { - "type": { - "description": "The value will always be `error`.", + "type": { + "description": "The value will always be `error`.", + "type": "string", + "example": "error", + "enum": [ + "error" + ], + "nullable": false + }, + "status": { + "description": "The HTTP status of the response.", + "type": "integer", + "format": "int32", + "example": 400, + "nullable": false + }, + "code": { + "description": "A Box-specific error code.", + "type": "string", + "example": "item_name_invalid", + "enum": [ + "created", + "accepted", + "no_content", + "redirect", + "not_modified", + "bad_request", + "unauthorized", + "forbidden", + "not_found", + "method_not_allowed", + "conflict", + "precondition_failed", + "too_many_requests", + "internal_server_error", + "unavailable", + "item_name_invalid", + "insufficient_scope" + ] + }, + "message": { + "description": "A short message describing the error.", + "type": "string", + "example": "Method Not Allowed", + "nullable": false + }, + "context_info": { + "description": "A free-form object that contains additional context\nabout the error. The possible fields are defined on\na per-endpoint basis. `message` is only one example.", + "type": "object", + "example": { + "message": "Something went wrong" + }, + "additionalProperties": {}, + "nullable": true + }, + "help_url": { + "description": "A URL that links to more information about why this error occurred.", + "type": "string", + "example": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/", + "nullable": false + }, + "request_id": { + "description": "A unique identifier for this response, which can be used\nwhen contacting Box support.", + "type": "string", + "example": "abcdef123456", + "nullable": false + } + }, + "title": "Client error", + "x-box-resource-id": "client_error_v2025.0" + }, + "DocGenBatch--Base": { + "description": "The basic representation of a Box Doc Gen batch object. A Box Doc Gen batch contains one or more Box Doc Gen jobs.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier that represents a Box Doc Gen batch.", + "type": "string", + "example": "12345", + "nullable": false + }, + "type": { + "description": "The value will always be `docgen_batch`.", + "type": "string", + "example": "docgen_batch", + "enum": [ + "docgen_batch" + ], + "nullable": false + } + }, + "required": [ + "id", + "type" + ], + "title": "Box Doc Gen batch (Base)", + "x-box-resource-id": "docgen_batch_v2025.0--base", + "x-box-tag": "docgen", + "x-box-variant": "base", + "x-box-variants": [ + "base" + ] + }, + "DocGenBatchCreateRequest": { + "description": "The schema for creating a Box Doc Gen job batch request.", + "type": "object", + "properties": { + "file": { + "allOf": [ + { + "$ref": "#/components/schemas/FileReference" + }, + { + "description": "A Box Doc Gen template that is used to generate the document." + } + ] + }, + "file_version": { + "allOf": [ + { + "$ref": "#/components/schemas/FileVersion--Base" + }, + { + "description": "File version of a template." + } + ] + }, + "input_source": { + "description": "Source of input. The value has to be `api` for all the API-based document generation requests.", + "type": "string", + "example": "api" + }, + "destination_folder": { + "allOf": [ + { + "title": "Folder reference", + "type": "object", + "description": "Folder reference.", + "required": [ + "type", + "id" + ], + "properties": { + "type": { + "description": "The value will always be `folder`.", + "type": "string", + "example": "folder", + "enum": [ + "folder" + ], + "nullable": false + }, + "id": { + "description": "ID of the folder.", + "type": "string", + "example": "42037322" + } + } + }, + { + "description": "Destination folder for the generated files." + } + ] + }, + "output_type": { + "description": "Type of the output file.", + "type": "string", + "example": "docx" + }, + "document_generation_data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DocGenDocumentGenerationData" + } + } + }, + "required": [ + "file", + "input_source", + "destination_folder", + "output_type", + "document_generation_data" + ], + "title": "Create batch request" + }, + "DocGenDocumentGenerationData": { + "description": "The schema for for creating a Box Doc Gen job request.", + "type": "object", + "properties": { + "generated_file_name": { + "description": "File name of the output file.", + "type": "string", + "example": "New_Template" + }, + "user_input": { + "type": "object", + "example": { + "name": "Aaron Levie" + }, + "additionalProperties": {} + } + }, + "required": [ + "generated_file_name", + "user_input" + ], + "title": "Document generation data" + }, + "DocGenJob": { + "description": "A standard representation of a Box Doc Gen job.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/DocGenJob--Base" + }, + { + "properties": { + "batch": { + "allOf": [ + { + "$ref": "#/components/schemas/DocGenBatch--Base" + }, + { + "description": "Box Doc Gen batch that the job belongs to." + } + ] + }, + "template_file": { + "allOf": [ + { + "$ref": "#/components/schemas/FileReference" + }, + { + "description": "Box Doc Gen template used in the job." + } + ] + }, + "template_file_version": { + "allOf": [ + { + "$ref": "#/components/schemas/FileVersion--Base" + }, + { + "description": "File version of a template." + } + ] + }, + "output_file": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/FileReference" + }, + { + "title": "OpenAPI 3.0 null schema type", + "description": "The definition for a null schema type in OpenAPI `3.0`.", + "type": "object", + "nullable": true, + "additionalProperties": false + } + ] + }, + { + "description": "The output file of the job. This property is `null` until the job is completed." + } + ] + }, + "output_file_version": { + "allOf": [ + { + "oneOf": [ + { + "$ref": "#/components/schemas/FileVersion--Base" + }, + { + "title": "OpenAPI 3.0 null schema type", + "description": "The definition for a null schema type in OpenAPI `3.0`.", + "type": "object", + "nullable": true, + "additionalProperties": false + } + ] + }, + { + "description": "File version of the output file. This property is `null` until the job is completed." + } + ] + }, + "status": { + "description": "Status of the job.", + "type": "string", + "example": "completed", + "enum": [ + "submitted", + "completed", + "failed", + "completed_with_error", + "pending" + ] + }, + "output_type": { + "description": "Type of the generated file.", + "type": "string", + "example": "docx" + } + } + } + ], + "required": [ + "id", + "batch", + "template_file", + "template_file_version", + "status", + "output_type" + ], + "title": "Box Doc Gen job", + "x-box-resource-id": "docgen_job_v2025.0", + "x-box-tag": "docgen", + "x-box-variant": "standard", + "x-box-variants": [ + "base", + "standard", + "full" + ] + }, + "DocGenJob--Base": { + "description": "The basic representation of a Box Doc Gen job.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier that represent a Box Doc Gen job.", + "type": "string", + "example": "12345", + "nullable": false + }, + "type": { + "description": "The value will always be `docgen_job`.", + "type": "string", + "example": "docgen_job", + "enum": [ + "docgen_job" + ], + "nullable": false + } + }, + "required": [ + "id", + "type" + ], + "title": "Box Doc Gen job (Base)", + "x-box-resource-id": "docgen_job_v2025.0--base", + "x-box-tag": "docgen", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard", + "full" + ] + }, + "DocGenJob--Full": { + "description": "A full representation of a Box Doc Gen job.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/DocGenJob" + }, + { + "properties": { + "created_at": { + "description": "Time of job creation.", + "type": "string", + "example": "2022-05-11T10:56:11-07:00", + "readOnly": true + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "User who created the job." + } + ] + }, + "enterprise": { + "allOf": [ + { + "$ref": "#/components/schemas/EnterpriseReference" + }, + { + "description": "ID of the enterprise." + } + ] + }, + "source": { + "description": "Source of the request.", + "type": "string", + "example": "api", + "readOnly": true + } + } + } + ], + "required": [ + "id", + "batch", + "created_by", + "enterprise", + "template_file", + "template_file_version", + "output_type", + "source", + "status" + ], + "title": "Box Doc Gen job (Full)", + "x-box-resource-id": "docgen_job_v2025.0--full", + "x-box-tag": "docgen", + "x-box-variant": "full", + "x-box-variants": [ + "base", + "standard", + "full" + ] + }, + "DocGenJobs": { + "description": "A list of Box Doc Gen jobs with a standard set of parameters.", + "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": "List of jobs.", + "type": "array", + "items": { + "$ref": "#/components/schemas/DocGenJob" + } + } + } + } + ], + "title": "Box Doc Gen jobs", + "x-box-resource-id": "docgen_jobs_v2025.0", + "x-box-tag": "docgen", + "x-box-variant": "base", + "x-box-variants": [ + "standard", + "full" + ] + }, + "DocGenJobs--Full": { + "description": "A list of Box Doc Gen jobs with a full set of parameters.", + "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": "List of jobs.", + "type": "array", + "items": { + "$ref": "#/components/schemas/DocGenJob--Full" + } + } + } + } + ], + "title": "Box Doc Gen jobs (Full)", + "x-box-resource-id": "docgen_jobs_v2025.0--full", + "x-box-tag": "docgen", + "x-box-variant": "full", + "x-box-variants": [ + "standard", + "full" + ] + }, + "DocGenTag": { + "description": "A Box Doc Gen template tag object.", + "type": "object", + "properties": { + "tag_content": { + "description": "The content of the tag.", + "type": "string", + "example": "{{item.name}}", + "readOnly": true + }, + "tag_type": { + "description": "Type of the tag.", + "type": "string", + "example": "text", + "enum": [ + "text", + "arithmetic", + "conditional", + "for-loop", + "table-loop", + "image" + ], + "readOnly": true + }, + "json_paths": { + "description": "List of the paths.", + "type": "array", + "items": { + "readOnly": true, + "type": "string", + "example": "products.name" + }, + "example": [ + "products", + "products.name" + ], + "readOnly": true + } + }, + "required": [ + "tag_content", + "tag_type", + "json_paths" + ], + "title": "Box Doc Gen template tag", + "x-box-resource-id": "docgen_tag_v2025.0", + "x-box-sanitized": true, + "x-box-tag": "docgen_template" + }, + "DocGenTags": { + "description": "A list of Box Doc Gen tags.", + "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": "List of tags.", + "type": "array", + "items": { + "$ref": "#/components/schemas/DocGenTag" + } + } + } + } + ], + "title": "Box Doc Gen tags", + "x-box-resource-id": "docgen_tags_v2025.0", + "x-box-tag": "docgen_template" + }, + "DocGenTagsProcessingMessage": { + "description": "A message informing the user that document tags are still being processed.", + "type": "object", + "properties": { + "message": { + "description": "A message informing the user that document tags are still being processed.", "type": "string", - "example": "error", - "enum": [ - "error" - ], - "nullable": false + "example": "Processing tags for this file.", + "readOnly": true + } + }, + "required": [ + "message" + ], + "title": "Box Doc Gen tags processing message", + "x-box-resource-id": "docgen_tags_processing_message_v2025.0", + "x-box-tag": "docgen_template" + }, + "DocGenTemplate": { + "description": "A Box Doc Gen template object.", + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/DocGenTemplate--Base" }, - "status": { - "description": "The HTTP status of the response.", - "type": "integer", - "format": "int32", - "example": 400, - "nullable": false + { + "properties": { + "file_name": { + "description": "The name of the template.", + "type": "string", + "example": "Official contract", + "nullable": true + } + } + } + ], + "title": "Box Doc Gen template", + "x-box-resource-id": "docgen_template_v2025.0", + "x-box-tag": "docgen_template", + "x-box-variant": "standard", + "x-box-variants": [ + "base", + "standard" + ] + }, + "DocGenTemplate--Base": { + "description": "A base representation of a Box Doc Gen template, used when\nnested within another resource.", + "type": "object", + "properties": { + "file": { + "allOf": [ + { + "$ref": "#/components/schemas/FileReference" + }, + { + "description": "Enable the file to generate a document from." + } + ] + } + }, + "title": "Box Doc Gen template (Base)", + "x-box-resource-id": "docgen_template_v2025.0--base", + "x-box-variant": "base", + "x-box-variants": [ + "base", + "standard" + ] + }, + "DocGenTemplateCreateRequest": { + "description": "The schema for marking document as Box Doc Gen template.", + "type": "object", + "properties": { + "file": { + "allOf": [ + { + "$ref": "#/components/schemas/FileReference" + }, + { + "description": "Marks the file as a Box Doc Gen template to generate the document from." + } + ] + } + }, + "required": [ + "file" + ], + "title": "Mark file as Box Doc Gen template" + }, + "DocGenTemplates": { + "description": "List of Box Doc Gen 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 + } + } }, - "code": { - "description": "A Box-specific error code.", + { + "properties": { + "entries": { + "description": "A list of templates.", + "type": "array", + "items": { + "$ref": "#/components/schemas/DocGenTemplate" + } + } + } + } + ], + "title": "Box Doc Gen templates", + "x-box-resource-id": "docgen_templates_v2025.0", + "x-box-tag": "docgen_template" + }, + "EnterpriseReference": { + "description": "A reference to an enterprise, used when\nnested within another resource.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier for this enterprise.", "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" - ] + "example": "1910967" }, - "message": { - "description": "A short message describing the error.", + "type": { + "description": "The value will always be `enterprise`.", "type": "string", - "example": "Method Not Allowed", + "example": "enterprise", + "enum": [ + "enterprise" + ], "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", - "example": { - "message": "Something went wrong" - }, - "additionalProperties": {}, - "nullable": true - }, - "help_url": { - "description": "A URL that links to more information about why this error occurred.", + } + }, + "title": "Enterprise reference" + }, + "FileReference": { + "description": "File reference.", + "type": "object", + "properties": { + "type": { + "description": "The value will always be `file`.", "type": "string", - "example": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/", + "example": "file", + "enum": [ + "file" + ], "nullable": false }, - "request_id": { - "description": "A unique identifier for this response, which can be used\nwhen contacting Box support.", + "id": { + "description": "ID of the object.", "type": "string", - "example": "abcdef123456", + "example": "42037322", "nullable": false } }, - "title": "Client error", - "x-box-resource-id": "client_error_v2025.0" + "required": [ + "type", + "id" + ], + "title": "File reference" }, - "DocGenBatch--Base": { - "description": "The basic representation of a Box Doc Gen batch object. A Box Doc Gen batch contains one or more Box Doc Gen jobs.", + "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 represents a Box Doc Gen batch.", + "description": "The unique identifier that represent a file version.", "type": "string", "example": "12345", "nullable": false }, "type": { - "description": "The value will always be `docgen_batch`.", + "description": "The value will always be `file_version`.", "type": "string", - "example": "docgen_batch", + "example": "file_version", "enum": [ - "docgen_batch" + "file_version" ], "nullable": false } @@ -1267,620 +2658,413 @@ "id", "type" ], - "title": "Box Doc Gen batch (Base)", - "x-box-resource-id": "docgen_batch_v2025.0--base", - "x-box-tag": "docgen", - "x-box-variant": "base", - "x-box-variants": [ - "base" - ] + "title": "File version (Base)" }, - "DocGenBatchCreateRequest": { - "description": "The schema for creating a Box Doc Gen job batch request.", + "Group--Base": { + "description": "A base representation of a group.", "type": "object", "properties": { - "file": { - "allOf": [ - { - "$ref": "#/components/schemas/FileReference" - }, - { - "description": "A Box Doc Gen template that is used to generate the document." - } - ] - }, - "file_version": { - "allOf": [ - { - "$ref": "#/components/schemas/FileVersion--Base" - }, - { - "description": "File version of a template." - } - ] - }, - "input_source": { - "description": "Source of input. The value has to be `api` for all the API-based document generation requests.", - "type": "string", - "example": "api" - }, - "destination_folder": { - "allOf": [ - { - "title": "Folder reference", - "type": "object", - "description": "Folder reference.", - "required": [ - "type", - "id" - ], - "properties": { - "type": { - "description": "The value will always be `folder`.", - "type": "string", - "example": "folder", - "enum": [ - "folder" - ], - "nullable": false - }, - "id": { - "description": "ID of the folder.", - "type": "string", - "example": "42037322" - } - } - }, - { - "description": "Destination folder for the generated files." - } - ] - }, - "output_type": { - "description": "Type of the output file.", + "id": { + "description": "The unique identifier for this object.", "type": "string", - "example": "docx" + "example": "11446498" }, - "document_generation_data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DocGenDocumentGenerationData" - } - } - }, - "required": [ - "file", - "input_source", - "destination_folder", - "output_type", - "document_generation_data" - ], - "title": "Create batch request" - }, - "DocGenDocumentGenerationData": { - "description": "The schema for for creating a Box Doc Gen job request.", - "type": "object", - "properties": { - "generated_file_name": { - "description": "File name of the output file.", + "type": { + "description": "The value will always be `group`.", "type": "string", - "example": "New_Template" - }, - "user_input": { - "type": "object", - "example": { - "name": "Aaron Levie" - }, - "additionalProperties": {} + "example": "group", + "enum": [ + "group" + ] } }, "required": [ - "generated_file_name", - "user_input" + "id", + "type" ], - "title": "Document generation data" + "title": "Group (Base)" }, - "DocGenJob": { - "description": "A standard representation of a Box Doc Gen job.", + "Group--Mini": { + "description": "Mini representation of a group, including id and name of\ngroup.", "type": "object", "allOf": [ { - "$ref": "#/components/schemas/DocGenJob--Base" + "$ref": "#/components/schemas/Group--Base" }, { "properties": { - "batch": { - "allOf": [ - { - "$ref": "#/components/schemas/DocGenBatch--Base" - }, - { - "description": "Box Doc Gen batch that the job belongs to." - } - ] - }, - "template_file": { - "allOf": [ - { - "$ref": "#/components/schemas/FileReference" - }, - { - "description": "Box Doc Gen template used in the job." - } - ] - }, - "template_file_version": { - "allOf": [ - { - "$ref": "#/components/schemas/FileVersion--Base" - }, - { - "description": "File version of a template." - } - ] - }, - "output_file": { - "allOf": [ - { - "oneOf": [ - { - "$ref": "#/components/schemas/FileReference" - }, - { - "title": "OpenAPI 3.0 null schema type", - "description": "The definition for a null schema type in OpenAPI `3.0`.", - "type": "object", - "nullable": true, - "additionalProperties": false - } - ] - }, - { - "description": "The output file of the job. This property is `null` until the job is completed." - } - ] - }, - "output_file_version": { - "allOf": [ - { - "oneOf": [ - { - "$ref": "#/components/schemas/FileVersion--Base" - }, - { - "title": "OpenAPI 3.0 null schema type", - "description": "The definition for a null schema type in OpenAPI `3.0`.", - "type": "object", - "nullable": true, - "additionalProperties": false - } - ] - }, - { - "description": "File version of the output file. This property is `null` until the job is completed." - } - ] - }, - "status": { - "description": "Status of the job.", + "name": { + "description": "The name of the group.", "type": "string", - "example": "completed", - "enum": [ - "submitted", - "completed", - "failed", - "completed_with_error", - "pending" - ] + "example": "Support" }, - "output_type": { - "description": "Type of the generated file.", + "group_type": { + "description": "The type of the group.", "type": "string", - "example": "docx" - } - } - } - ], - "required": [ - "id", - "batch", - "template_file", - "template_file_version", - "status", - "output_type" - ], - "title": "Box Doc Gen job", - "x-box-resource-id": "docgen_job_v2025.0", - "x-box-tag": "docgen", - "x-box-variant": "standard", - "x-box-variants": [ - "base", - "standard", - "full" - ] - }, - "DocGenJob--Base": { - "description": "The basic representation of a Box Doc Gen job.", - "type": "object", - "properties": { - "id": { - "description": "The unique identifier that represent a Box Doc Gen job.", - "type": "string", - "example": "12345", - "nullable": false - }, - "type": { - "description": "The value will always be `docgen_job`.", - "type": "string", - "example": "docgen_job", - "enum": [ - "docgen_job" - ], - "nullable": false + "example": "managed_group", + "enum": [ + "managed_group", + "all_users_group" + ] + } + } } - }, - "required": [ - "id", - "type" ], - "title": "Box Doc Gen job (Base)", - "x-box-resource-id": "docgen_job_v2025.0--base", - "x-box-tag": "docgen", - "x-box-variant": "base", - "x-box-variants": [ - "base", - "standard", - "full" - ] + "title": "Group (Mini)" }, - "DocGenJob--Full": { - "description": "A full representation of a Box Doc Gen job.", + "Hub": { + "description": "A standard representation of a hub, as returned from any\nhubs API endpoints by default.", "type": "object", "allOf": [ { - "$ref": "#/components/schemas/DocGenJob" + "$ref": "#/components/schemas/Hub--Base" }, { "properties": { + "title": { + "description": "The title given to the hub.", + "type": "string", + "example": "Contracts" + }, + "description": { + "description": "The description of the hub. First 200 characters are returned.", + "type": "string", + "example": "All the contracts for the company." + }, "created_at": { - "description": "Time of job creation.", + "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", - "example": "2022-05-11T10:56:11-07:00", - "readOnly": true + "format": "date-time", + "example": "2012-12-12T10:53:43Z" + }, + "updated_at": { + "description": "The date and time when the hub was last updated.", + "type": "string", + "format": "date-time", + "example": "2012-12-12T10:53:43Z" }, "created_by": { "allOf": [ { - "$ref": "#/components/schemas/User--Base" + "$ref": "#/components/schemas/User--Mini" }, { - "description": "User who created the job." + "description": "The user who created this hub." } ] }, - "enterprise": { + "updated_by": { "allOf": [ { - "$ref": "#/components/schemas/EnterpriseReference" + "$ref": "#/components/schemas/User--Mini" }, { - "description": "ID of the enterprise." + "description": "The user who last modified this hub." } ] }, - "source": { - "description": "Source of the request.", - "type": "string", - "example": "api", - "readOnly": true + "view_count": { + "description": "The number of views for the hub.", + "type": "integer", + "format": "int32", + "example": 506 + }, + "is_ai_enabled": { + "description": "Indicates if AI features are enabled for the hub.", + "type": "boolean", + "example": true + }, + "is_collaboration_restricted_to_enterprise": { + "description": "Indicates if collaboration is restricted to the enterprise.", + "type": "boolean", + "example": true + }, + "can_non_owners_invite": { + "description": "Indicates if non-owners can invite others to the hub.", + "type": "boolean", + "example": true + }, + "can_shared_link_be_created": { + "description": "Indicates if a shared link can be created for the hub.", + "type": "boolean", + "example": true } } } ], - "required": [ - "id", - "batch", - "created_by", - "enterprise", - "template_file", - "template_file_version", - "output_type", - "source", - "status" - ], - "title": "Box Doc Gen job (Full)", - "x-box-resource-id": "docgen_job_v2025.0--full", - "x-box-tag": "docgen", - "x-box-variant": "full", - "x-box-variants": [ - "base", - "standard", - "full" - ] + "title": "Hub", + "x-box-resource-id": "hub_v2025.0", + "x-box-variant": "standard" }, - "DocGenJobs": { - "description": "A list of Box Doc Gen jobs with a standard set of parameters.", + "Hub--Base": { + "description": "The bare basic representation of a hub.", "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": { + "id": { + "description": "The unique identifier that represent a hub.\n\nThe ID for any hub can be determined\nby visiting a hub in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/hubs/123`\nthe `hub_id` is `123`.", + "type": "string", + "example": "12345" }, - { - "properties": { - "entries": { - "description": "List of jobs.", - "type": "array", - "items": { - "$ref": "#/components/schemas/DocGenJob" - } - } - } + "type": { + "description": "The value will always be `hubs`.", + "type": "string", + "example": "hubs", + "enum": [ + "hubs" + ] } + }, + "required": [ + "id", + "type" ], - "title": "Box Doc Gen jobs", - "x-box-resource-id": "docgen_jobs_v2025.0", - "x-box-tag": "docgen", + "title": "Hub (Base)", + "x-box-resource-id": "hub_v2025.0--base", + "x-box-tag": "hubs", "x-box-variant": "base", "x-box-variants": [ - "standard", - "full" + "base", + "standard" ] }, - "DocGenJobs--Full": { - "description": "A list of Box Doc Gen jobs with a full set of parameters.", + "HubAccessGrantee": { + "description": "The user or group that is granted access.", "type": "object", - "allOf": [ + "oneOf": [ { - "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 - } - } + "$ref": "#/components/schemas/HubCollaborationUser" }, { - "properties": { - "entries": { - "description": "List of jobs.", - "type": "array", - "items": { - "$ref": "#/components/schemas/DocGenJob--Full" - } - } - } + "$ref": "#/components/schemas/Group--Mini" } ], - "title": "Box Doc Gen jobs (Full)", - "x-box-resource-id": "docgen_jobs_v2025.0--full", - "x-box-tag": "docgen", - "x-box-variant": "full", - "x-box-variants": [ - "standard", - "full" - ] + "title": "Hub Accessible By" }, - "DocGenTag": { - "description": "A Box Doc Gen template tag object.", + "HubCollaboration": { + "description": "A hub collaboration object grants a user or group access \nto a hub with permissions defined by a specific role.", "type": "object", "properties": { - "tag_content": { - "description": "The content of the tag.", + "id": { + "description": "The unique identifier for this collaboration.", "type": "string", - "example": "{{item.name}}", - "readOnly": true + "example": "12345678" }, - "tag_type": { - "description": "Type of the tag.", + "type": { + "description": "The value will always be `hub_collaboration`.", "type": "string", - "example": "text", + "example": "hub_collaboration", "enum": [ - "text", - "arithmetic", - "conditional", - "for-loop", - "table-loop", - "image" - ], - "readOnly": true + "hub_collaboration" + ] }, - "json_paths": { - "description": "List of the paths.", - "type": "array", - "items": { - "readOnly": true, - "type": "string", - "example": "products.name" - }, - "example": [ - "products", - "products.name" - ], - "readOnly": true + "hub": { + "$ref": "#/components/schemas/Hub--Base" + }, + "accessible_by": { + "$ref": "#/components/schemas/HubAccessGrantee" + }, + "role": { + "description": "The level of access granted to hub.\nPossible values are `editor`, `viewer`, and `co-owner`.", + "type": "string", + "example": "editor" + }, + "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" + ] + }, + "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, or enforces\nan exposed password detection for the external collaborators.", + "type": "boolean", + "example": true + }, + "user_has_strong_password": { + "description": "Whether or not the user has a strong and not exposed password set\nfor their account. The field is `null` when a strong password is\nnot required.", + "type": "boolean", + "example": true, + "nullable": true + } + } + }, + "two_factor_authentication_requirement": { + "type": "object", + "properties": { + "enterprise_has_two_factor_auth_enabled": { + "description": "Whether or not the enterprise that owns the content requires\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": [ - "tag_content", - "tag_type", - "json_paths" + "id", + "type" ], - "title": "Box Doc Gen template tag", - "x-box-resource-id": "docgen_tag_v2025.0", - "x-box-sanitized": true, - "x-box-tag": "docgen_template" + "title": "Hub Collaboration", + "x-box-resource-id": "hub_collaboration_v2025.0", + "x-box-tag": "hub_collaborations" }, - "DocGenTags": { - "description": "A list of Box Doc Gen tags.", + "HubCollaborationCreateRequest": { + "description": "Request body for creating a new Hub collaboration.", "type": "object", - "allOf": [ - { + "properties": { + "hub": { + "description": "Hubs reference.", "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": { + "description": "The value will always be `hubs`.", "type": "string", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", - "nullable": true + "example": "hubs", + "enum": [ + "hubs" + ] }, - "prev_marker": { - "description": "The marker for the start of the previous page of results.", + "id": { + "description": "ID of the object.", "type": "string", - "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", - "nullable": true + "example": "42037322" } - } + }, + "required": [ + "type", + "id" + ], + "title": "Hubs reference" }, - { + "accessible_by": { + "description": "The user or group who gets access to the item.", + "type": "object", "properties": { - "entries": { - "description": "List of tags.", - "type": "array", - "items": { - "$ref": "#/components/schemas/DocGenTag" - } + "type": { + "description": "The type of collaborator to invite.\nPossible values are `user` or `group`.", + "type": "string", + "example": "user" + }, + "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 who gets 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 to hub.\nPossible values are `editor`, `viewer`, and `co-owner`.", + "type": "string", + "example": "editor" } + }, + "required": [ + "hub", + "accessible_by", + "role" ], - "title": "Box Doc Gen tags", - "x-box-resource-id": "docgen_tags_v2025.0", - "x-box-tag": "docgen_template" + "title": "Hub Collaboration Create Request" }, - "DocGenTagsProcessingMessage": { - "description": "A message informing the user that document tags are still being processed.", + "HubCollaborationUpdateRequest": { + "description": "Request body for updating an existing Hub collaboration.", "type": "object", "properties": { - "message": { - "description": "A message informing the user that document tags are still being processed.", + "role": { + "description": "The level of access granted to hub.\nPossible values are `editor`, `viewer`, and `co-owner`.", "type": "string", - "example": "Processing tags for this file.", - "readOnly": true + "example": "editor" } }, - "required": [ - "message" - ], - "title": "Box Doc Gen tags processing message", - "x-box-resource-id": "docgen_tags_processing_message_v2025.0", - "x-box-tag": "docgen_template" + "title": "Hub Collaboration Update Request" }, - "DocGenTemplate": { - "description": "A Box Doc Gen template object.", + "HubCollaborationUser": { + "description": "A mini representation of a user, can be returned only when\nthe status is `pending`.", "type": "object", "allOf": [ { - "$ref": "#/components/schemas/DocGenTemplate--Base" + "$ref": "#/components/schemas/User--Base" }, { "properties": { - "file_name": { - "description": "The name of the template.", + "name": { + "description": "The display name of this user. If the collaboration status is `pending`, an empty string is returned.", "type": "string", - "example": "Official contract", - "nullable": true - } - } - } - ], - "title": "Box Doc Gen template", - "x-box-resource-id": "docgen_template_v2025.0", - "x-box-tag": "docgen_template", - "x-box-variant": "standard", - "x-box-variants": [ - "base", - "standard" - ] - }, - "DocGenTemplate--Base": { - "description": "A base representation of a Box Doc Gen template, used when\nnested within another resource.", - "type": "object", - "properties": { - "file": { - "allOf": [ - { - "$ref": "#/components/schemas/FileReference" - }, - { - "description": "Enable the file to generate a document from." - } - ] - } - }, - "title": "Box Doc Gen template (Base)", - "x-box-resource-id": "docgen_template_v2025.0--base", - "x-box-variant": "base", - "x-box-variants": [ - "base", - "standard" - ] - }, - "DocGenTemplateCreateRequest": { - "description": "The schema for marking document as Box Doc Gen template.", - "type": "object", - "properties": { - "file": { - "allOf": [ - { - "$ref": "#/components/schemas/FileReference" + "example": "Aaron Levie", + "maxLength": 50, + "nullable": false }, - { - "description": "Marks the file as a Box Doc Gen template to generate the document from." + "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 } - ] + } } - }, - "required": [ - "file" ], - "title": "Mark file as Box Doc Gen template" + "title": "Hub Collaboration User" }, - "DocGenTemplates": { - "description": "List of Box Doc Gen templates.", + "HubCollaborations": { + "description": "A list of hub collaborations.", "type": "object", "allOf": [ + { + "properties": { + "entries": { + "description": "A list of hub collaborations.", + "type": "array", + "items": { + "$ref": "#/components/schemas/HubCollaboration" + } + } + } + }, { "type": "object", "description": "The part of an API response that describes marker\nbased pagination.", @@ -1896,103 +3080,51 @@ "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 } } - }, + } + ], + "title": "Hub Collaborations", + "x-box-resource-id": "hub_collaborations_v2025.0", + "x-box-tag": "hub_collaborations" + }, + "Hubs": { + "description": "A paginated list of hubs.", + "type": "object", + "allOf": [ { "properties": { "entries": { - "description": "A list of templates.", + "description": "A list of hubs.", "type": "array", "items": { - "$ref": "#/components/schemas/DocGenTemplate" + "$ref": "#/components/schemas/Hub" } } } - } - ], - "title": "Box Doc Gen templates", - "x-box-resource-id": "docgen_templates_v2025.0", - "x-box-tag": "docgen_template" - }, - "EnterpriseReference": { - "description": "A reference to an enterprise, used when\nnested within another resource.", - "type": "object", - "properties": { - "id": { - "description": "The unique identifier for this enterprise.", - "type": "string", - "example": "1910967" - }, - "type": { - "description": "The value will always be `enterprise`.", - "type": "string", - "example": "enterprise", - "enum": [ - "enterprise" - ], - "nullable": false - } - }, - "title": "Enterprise reference" - }, - "FileReference": { - "description": "File reference.", - "type": "object", - "properties": { - "type": { - "description": "The value will always be `file`.", - "type": "string", - "example": "file", - "enum": [ - "file" - ], - "nullable": false - }, - "id": { - "description": "ID of the object.", - "type": "string", - "example": "42037322", - "nullable": false - } - }, - "required": [ - "type", - "id" - ], - "title": "File reference" - }, - "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": "The value will always be `file_version`.", - "type": "string", - "example": "file_version", - "enum": [ - "file_version" - ], - "nullable": false + { + "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 + } + } } - }, - "required": [ - "id", - "type" ], - "title": "File version (Base)" + "title": "Hubs", + "x-box-resource-id": "hubs_v2025.0", + "x-box-tag": "hubs" }, "ShieldList": { "description": "A standard representation of a Shield List.", @@ -2409,6 +3541,30 @@ "title": "Create Shield List update request", "x-box-tag": "shield_lists" }, + "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": "The value will always be `terms_of_service`.", + "type": "string", + "example": "terms_of_service", + "enum": [ + "terms_of_service" + ] + } + }, + "required": [ + "id", + "type" + ], + "title": "Terms of service (Base)" + }, "User--Base": { "description": "A mini representation of a user, used when\nnested within another resource.", "type": "object", @@ -2433,6 +3589,32 @@ "id" ], "title": "User (Base)" + }, + "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 + }, + "login": { + "description": "The primary email address of this user.", + "type": "string", + "format": "email", + "example": "ceo@example.com" + } + } + } + ], + "title": "User (Mini)" } }, "securitySchemes": { @@ -2474,6 +3656,16 @@ "description": "Doc Gen templates are used as input to generate documents.", "x-box-tag": "docgen_template" }, + { + "name": "Hubs", + "description": "A set of endpoints used to manage Hubs.", + "x-box-tag": "hubs" + }, + { + "name": "Hub Collaborations", + "description": "A set of endpoints used to manage collaborations within a Hub.", + "x-box-tag": "hub_collaborations" + }, { "name": "Shield lists", "description": "Shield List allow an administrator to create a list \nwhich will be shared between different\nShield Smart Access and Threat Prection rules.", diff --git a/openapi/openapi.json b/openapi/openapi.json index 2aa5c8cf..4bcf333c 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -14,7 +14,7 @@ "url": "http://www.apache.org/licenses/LICENSE-2.0" }, "version": "2024.0", - "x-box-commit-hash": "eff357f39b" + "x-box-commit-hash": "f40de715da" }, "servers": [ {