From f0a1073a814157cbe0a5d35001e0c7027b4b9f49 Mon Sep 17 00:00:00 2001 From: box-apimgmt Date: Thu, 23 Jul 2026 13:07:16 -0700 Subject: [PATCH] docs: Query insights API --- openapi.json | 83 +++- openapi/openapi-v2025.0.json | 2 +- openapi/openapi-v2026.0.json | 798 ++++++++++++++++++++++++++++++++++- openapi/openapi.json | 83 +++- 4 files changed, 960 insertions(+), 6 deletions(-) diff --git a/openapi.json b/openapi.json index b0408a55..85f5d08f 100644 --- a/openapi.json +++ b/openapi.json @@ -14,7 +14,7 @@ "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "2024.0", - "x-box-commit-hash": "5a03ed238f" + "x-box-commit-hash": "92c221bf9d" }, "servers": [ { @@ -31889,6 +31889,49 @@ "type": "boolean", "example": true, "nullable": false + }, + "collections": { + "description": "The collections that this file belongs to.\n\nFor more information, see the\n[collections guide](https://developer.box.com/guides/collections).", + "type": "array", + "items": { + "$ref": "#/components/schemas/Collection" + } + }, + "is_download_available": { + "description": "Whether the file's binary content is eligible to be downloaded.\n\nThis is a content-level flag and does not reflect whether the\ncurrent user is authorized to download the file. Use\n`permissions.can_download`, when available, for that.", + "type": "boolean", + "example": true + }, + "download_url": { + "description": "A pre-authorized, expiring URL for directly downloading the file's\ncontent. Requires authentication and is valid only for the current\nsession.\n\nThis field is only returned for files, not folders or web links.", + "type": "string", + "format": "url", + "example": "https://dl.boxcloud.com/d/1/example_token/download" + }, + "authenticated_download_url": { + "description": "A stable API URL for the file content endpoint,\n`/2.0/files/{id}/content`. Unlike `download_url`, authorization is\nevaluated when the URL is requested with a valid access token.\n\nThis field is only returned for files, not folders or web links.", + "type": "string", + "format": "url", + "example": "https://api.box.com/2.0/files/12345/content" + }, + "allowed_shared_link_access_levels": { + "description": "The shared link access levels the authenticated user is allowed to\nuse when creating or updating a shared link for this file.\n\nThe list depends on item policy and user authorization, so it may be\nnarrower than the levels available to the owner. An empty array means\nno access level is available to this user.", + "type": "array", + "items": { + "title": "Shared link access level", + "type": "string", + "description": "The access level for a shared link.", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ] + }, + "example": [ + "open" + ], + "nullable": false } } } @@ -33394,10 +33437,13 @@ ] }, "allowed_shared_link_access_levels": { - "description": "A list of access levels that are available\nfor this folder.\n\nFor some folders, like the root folder, this will always\nbe an empty list as sharing is not allowed at that level.", + "description": "The shared link access levels the authenticated user is allowed to\nuse when creating or updating a shared link for this folder.\n\nThe list depends on item policy and user authorization. For some\nfolders, like the root folder, this is always empty as sharing is\nnot allowed at that level.", "type": "array", "items": { + "title": "Shared link access level", "type": "string", + "description": "The access level for a shared link.", + "example": "open", "enum": [ "open", "company", @@ -33509,6 +33555,13 @@ "type": "boolean", "example": true, "nullable": false + }, + "collections": { + "description": "The collections that this folder belongs to.\n\nFor more information, see the\n[collections guide](https://developer.box.com/guides/collections).", + "type": "array", + "items": { + "$ref": "#/components/schemas/Collection" + } } } } @@ -43355,6 +43408,32 @@ "trashed", "deleted" ] + }, + "collections": { + "description": "The collections that this web link belongs to.\n\nFor more information, see the\n[collections guide](https://developer.box.com/guides/collections).", + "type": "array", + "items": { + "$ref": "#/components/schemas/Collection" + } + }, + "allowed_shared_link_access_levels": { + "description": "The shared link access levels the authenticated user is allowed to\nuse when creating or updating a shared link for this web link.\n\nThe list depends on item policy and user authorization, so it may be\nnarrower than the levels available to the owner. An empty array means\nno access level is available to this user.", + "type": "array", + "items": { + "title": "Shared link access level", + "type": "string", + "description": "The access level for a shared link.", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ] + }, + "example": [ + "open" + ], + "nullable": false } } } diff --git a/openapi/openapi-v2025.0.json b/openapi/openapi-v2025.0.json index 662dac52..d463cd12 100644 --- a/openapi/openapi-v2025.0.json +++ b/openapi/openapi-v2025.0.json @@ -14,7 +14,7 @@ "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "2025.0", - "x-box-commit-hash": "5a03ed238f" + "x-box-commit-hash": "92c221bf9d" }, "servers": [ { diff --git a/openapi/openapi-v2026.0.json b/openapi/openapi-v2026.0.json index b0716522..1060b158 100644 --- a/openapi/openapi-v2026.0.json +++ b/openapi/openapi-v2026.0.json @@ -14,7 +14,7 @@ "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "2026.0", - "x-box-commit-hash": "5a03ed238f" + "x-box-commit-hash": "92c221bf9d" }, "servers": [ { @@ -284,6 +284,222 @@ "Convert to Box note" ] } + }, + "/query": { + "post": { + "operationId": "post_query_v2026.0", + "summary": "Query for Box items", + "description": "Runs a query to discover Box items using a logical predicate that can filter\nacross item fields and metadata templates. Results can be sorted, paginated,\nand shaped to include additional item or metadata fields.", + "parameters": [ + { + "$ref": "#/components/parameters/BoxVersionHeader" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryRequestBody" + } + } + } + }, + "responses": { + "200": { + "description": "Returns a paginated list of items matching the query.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryResults" + } + } + } + }, + "400": { + "description": "Returned when the query could not be parsed, the request body fails schema\nvalidation, a referenced scope is not valid, or an unexpected JSON type was\nprovided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header is\nmissing, not valid, or expired.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned when the query matched too many items, or too many inaccessible\nitems, to be processed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned when a referenced metadata template or item does not exist, or the\nuser does not have access to it.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "429": { + "description": "Returned when the enterprise exceeds the allowed request rate.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "500": { + "description": "Returned when an unexpected server error occurs while processing the query.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "query", + "tags": [ + "Query" + ] + } + }, + "/query_insights": { + "post": { + "operationId": "post_query_insights_v2026.0", + "summary": "Create insights for Box items", + "description": "Computes aggregated metrics over Box items matching a query predicate.\nFilters are applied first, followed by optional grouping, after which the\nrequested metrics (such as `sum`, `avg`, `min`, `max`, and `count`) are\ncomputed for each resulting group or over the entire filtered dataset.", + "parameters": [ + { + "$ref": "#/components/parameters/BoxVersionHeader" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryInsightsRequestBody" + } + } + } + }, + "responses": { + "200": { + "description": "Returns the computed insight entries.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryInsights" + } + } + } + }, + "400": { + "description": "Returned when the query could not be parsed, the request body fails schema\nvalidation, or an unexpected JSON type was provided.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "401": { + "description": "Returned when the access token provided in the `Authorization` header is\nmissing, not valid, or expired.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "403": { + "description": "Returned when the query is restricted for this enterprise or scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "404": { + "description": "Returned when a referenced metadata template does not exist, or the user\ndoes not have access to it.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "429": { + "description": "Returned when the enterprise exceeds the allowed request rate.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "500": { + "description": "Returned when an unexpected server error occurs while computing insights.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, + "default": { + "description": "An unexpected client error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + } + }, + "x-box-tag": "query", + "tags": [ + "Query" + ] + } } }, "components": { @@ -637,6 +853,581 @@ "x-box-resource-id": "notes_convert_created_file_v2026.0", "x-box-tag": "notes" }, + "QueryAncestorReference": { + "description": "A reference to an ancestor entity used to restrict query results to that\nentity and its recursive descendants.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier of the ancestor entity.", + "type": "string", + "example": "789" + }, + "type": { + "description": "The type of the ancestor entity. Possible value: folder.", + "type": "string", + "example": "folder" + } + }, + "additionalProperties": false, + "required": [ + "id", + "type" + ], + "title": "Query ancestor reference", + "x-box-tag": "query" + }, + "QueryInsightEntry": { + "description": "A single computed insight entry, containing its grouping keys (if applicable)\nand the computed metrics.", + "type": "object", + "properties": { + "key": { + "description": "The grouping key values associated with the entry. Contains one value per\n`group_by` field for `group` entries, and is empty for `overall` and\n`other` entries.", + "type": "array", + "items": { + "type": "string", + "example": "ContractType1" + }, + "example": [ + "ContractType1" + ] + }, + "type": { + "description": "The type of insight entry, indicating how the associated metrics are\naggregated.", + "type": "string", + "example": "group", + "enum": [ + "group", + "overall", + "other" + ] + }, + "metrics": { + "description": "A map of metric aliases to their computed results. For `other` entries, the\ncount is reported under the `totalCountBeyondTopGroups` key.", + "type": "object", + "example": { + "totalContractValue": { + "type": "sum", + "values": { + "sum": 180000 + } + }, + "countContractType": { + "type": "count", + "values": { + "count": 245 + } + } + }, + "additionalProperties": { + "$ref": "#/components/schemas/QueryInsightMetricResult" + } + } + }, + "additionalProperties": false, + "required": [ + "key", + "type", + "metrics" + ], + "title": "Query insight entry", + "x-box-resource-id": "query_insight_entry_v2026.0", + "x-box-tag": "query" + }, + "QueryInsightMetricResult": { + "description": "The computed result for a single metric, including the metric type and its\ncomputed value(s).", + "type": "object", + "properties": { + "type": { + "description": "The metric type that was computed.", + "type": "string", + "example": "sum" + }, + "values": { + "description": "The computed metric result(s), keyed by the metric function (for example\n`sum`, `avg`, `min`, `max`, or `count`).", + "type": "object", + "example": { + "sum": 50 + }, + "additionalProperties": { + "type": "number" + } + } + }, + "additionalProperties": false, + "required": [ + "type", + "values" + ], + "title": "Query insight metric result", + "x-box-tag": "query" + }, + "QueryInsights": { + "description": "The computed results of an insights request, as a list of insight entries.", + "type": "object", + "properties": { + "insights": { + "description": "The list of computed insight entries. Each entry corresponds to a group,\nthe overall dataset, or the aggregate of groups outside the top results.", + "type": "array", + "items": { + "$ref": "#/components/schemas/QueryInsightEntry" + } + } + }, + "example": { + "insights": [ + { + "key": [ + "ContractType1" + ], + "type": "group", + "metrics": { + "totalContractValue": { + "type": "sum", + "values": { + "sum": 180000 + } + }, + "countContractType": { + "type": "count", + "values": { + "count": 245 + } + } + } + }, + { + "key": [ + "ContractType4" + ], + "type": "group", + "metrics": { + "totalContractValue": { + "type": "sum", + "values": { + "sum": 100000 + } + }, + "countContractType": { + "type": "count", + "values": { + "count": 185 + } + } + } + }, + { + "key": [ + "ContractType2" + ], + "type": "group", + "metrics": { + "totalContractValue": { + "type": "sum", + "values": { + "sum": 200000 + } + }, + "countContractType": { + "type": "count", + "values": { + "count": 150 + } + } + } + }, + { + "key": [], + "type": "other", + "metrics": { + "totalCountBeyondTopGroups": { + "type": "count", + "values": { + "count": 165 + } + } + } + } + ] + }, + "additionalProperties": false, + "required": [ + "insights" + ], + "title": "Query insights", + "x-box-resource-id": "query_insights_v2026.0", + "x-box-tag": "query" + }, + "QueryInsightsGroupBy": { + "description": "Defines a single grouping criterion for an insights request. Currently only a\nsingle grouping field is supported.", + "type": "object", + "properties": { + "field": { + "description": "The fully qualified field name to group by. Supports metadata and item\nproperties.", + "type": "string", + "example": "enterprise_12345678:sales:contractType" + }, + "bucket_limit": { + "description": "The maximum number of buckets to return for the grouping. Defaults to `5`.", + "type": "integer", + "format": "int32", + "example": 3, + "default": 5, + "maximum": 10, + "minimum": 1 + } + }, + "additionalProperties": false, + "required": [ + "field" + ], + "title": "Query insights group by", + "x-box-tag": "query" + }, + "QueryInsightsMetricDefinition": { + "description": "Defines a single metric to compute, including the aggregation function and the\nfield it is applied to.", + "type": "object", + "properties": { + "type": { + "description": "The aggregation function to apply.", + "type": "string", + "example": "sum", + "enum": [ + "sum", + "avg", + "min", + "max", + "count" + ] + }, + "field": { + "description": "The fully qualified field name on which the metric is computed.", + "type": "string", + "example": "enterprise_12345678:sales:contractValue" + } + }, + "additionalProperties": false, + "required": [ + "type", + "field" + ], + "title": "Query insights metric definition", + "x-box-tag": "query" + }, + "QueryInsightsRequestBody": { + "description": "Request body describing the filtering, grouping, and metrics for an insights\ncomputation.", + "type": "object", + "properties": { + "query": { + "description": "The filtering and grouping definition. Filters are applied first, followed\nby grouping, before metrics are computed.", + "type": "object", + "additionalProperties": false, + "properties": { + "predicate": { + "description": "A logical expression used to filter the dataset prior to metric\ncomputation, similar to an SQL `WHERE` clause. May include\nnamed parameters referenced as `:placeholder`.", + "type": "string", + "example": "EXISTS(:templateArg) AND box:item:created_at >= :dateArg1 AND box:item:created_at < :dateArg2" + }, + "params": { + "description": "A map of placeholder names (without the `:` prefix) to their values.\nRequired only when the predicate contains parameter placeholders. The\ntype of each value must match the type of the field it is compared to.", + "type": "object", + "example": { + "templateArg": "enterprise_12345678:sales", + "dateArg1": "2025-06-01T00:00:00-07:00", + "dateArg2": "2025-07-01T00:00:00-07:00" + }, + "additionalProperties": {} + }, + "ancestors": { + "description": "Restricts results to items contained within any of the specified\nancestors. The user must have access to every listed ancestor. When\nomitted, insights are computed across all accessible items.", + "type": "array", + "items": { + "$ref": "#/components/schemas/QueryAncestorReference" + } + }, + "group_by": { + "description": "Defines how data is grouped for insights computation. Currently only a\nsingle grouping field is supported.", + "type": "array", + "items": { + "$ref": "#/components/schemas/QueryInsightsGroupBy" + } + } + }, + "required": [ + "predicate" + ] + }, + "metrics": { + "description": "A map of user-defined metric aliases to their definitions. A maximum of 10\nmetrics may be defined. Each alias must be a unique, non-empty string of up\nto 256 characters, containing only letters, digits, `_`, `-`, or `.`, and\nmust not start with a digit, `_`, `-`, or `.`. May be empty to request\nonly a total count.", + "type": "object", + "example": { + "totalContractValue": { + "type": "sum", + "field": "enterprise_12345678:sales:contractValue" + }, + "countContractType": { + "type": "count", + "field": "enterprise_12345678:sales:contractType" + } + }, + "additionalProperties": { + "$ref": "#/components/schemas/QueryInsightsMetricDefinition" + }, + "maxProperties": 10 + } + }, + "example": { + "query": { + "predicate": "EXISTS(:templateArg) AND box:item:created_at >= :dateArg1 AND box:item:created_at < :dateArg2", + "params": { + "templateArg": "enterprise_12345678:sales", + "dateArg1": "2025-06-01T00:00:00-07:00", + "dateArg2": "2025-07-01T00:00:00-07:00" + }, + "ancestors": [ + { + "id": "123", + "type": "folder" + } + ], + "group_by": [ + { + "field": "enterprise_12345678:sales:contractType", + "bucket_limit": 3 + } + ] + }, + "metrics": { + "totalContractValue": { + "type": "sum", + "field": "enterprise_12345678:sales:contractValue" + }, + "countContractType": { + "type": "count", + "field": "enterprise_12345678:sales:contractType" + } + } + }, + "additionalProperties": false, + "required": [ + "query", + "metrics" + ], + "title": "Query insights request body", + "x-box-tag": "query" + }, + "QueryOrderBy": { + "description": "A single sorting criterion applied to the query result set. Multiple criteria\nare applied sequentially in the order specified.", + "type": "object", + "properties": { + "field_key": { + "description": "The fully qualified field key to sort by.", + "type": "string", + "example": "enterprise_12345678:book:purchasePrice" + }, + "direction": { + "description": "The direction in which results are ordered.", + "type": "string", + "example": "asc", + "enum": [ + "asc", + "desc" + ] + } + }, + "additionalProperties": false, + "required": [ + "field_key", + "direction" + ], + "title": "Query order by", + "x-box-tag": "query" + }, + "QueryRequestBody": { + "description": "Request body describing the query to run, including the filtering predicate,\noptional sorting, pagination, and the fields to return for each result.", + "type": "object", + "properties": { + "query": { + "description": "The query definition, including the filtering predicate and its optional\nparameters and ancestor restrictions.", + "type": "object", + "additionalProperties": false, + "properties": { + "predicate": { + "description": "A logical expression used to filter the dataset, similar to an SQL\n`WHERE` clause. May include named parameters referenced as\n`:placeholder`.", + "type": "string", + "example": "enterprise_12345678:book:purchasePrice >= :price AND box:item:name = :name" + }, + "params": { + "description": "A map of placeholder names (without the `:` prefix) to their values.\nRequired only when the predicate contains parameter placeholders. The\ntype of each value must match the type of the field it is compared to.", + "type": "object", + "example": { + "price": 100, + "name": "The Hobbit" + }, + "additionalProperties": {} + }, + "ancestors": { + "description": "Restricts results to the specified ancestor entities and their\nrecursive descendants. The user must have read access to every listed\nancestor.", + "type": "array", + "items": { + "$ref": "#/components/schemas/QueryAncestorReference" + } + } + }, + "required": [ + "predicate" + ] + }, + "order_by": { + "description": "The sorting criteria for the result set. Entries are applied sequentially\nto define multi-level sorting.", + "type": "array", + "items": { + "$ref": "#/components/schemas/QueryOrderBy" + } + }, + "limit": { + "description": "The maximum number of results to return. Defaults to `50` when not\nprovided.", + "type": "integer", + "format": "int32", + "example": 1, + "default": 50, + "maximum": 100, + "minimum": 0 + }, + "fields": { + "description": "Controls which additional fields are included in each result entry. Each\nvalue must be one of: a fully qualified item field key (for example\n`box:item:name`), a metadata template key to hydrate the full template (for\nexample `enterprise_12345678:project`), or a specific metadata template\nfield key to hydrate a single field from the template (for example\n`enterprise_12345678:project:name`). When omitted, entries include only the\nitem type and identifier.", + "type": "array", + "items": { + "type": "string", + "example": "box:item:name" + }, + "example": [ + "box:item:name", + "enterprise_12345678:book" + ] + }, + "marker": { + "description": "An opaque token returned from a previous response, used to continue\nretrieval. When provided, all other request parameters must exactly match\nthose of the original request.", + "type": "string", + "example": "xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA=" + } + }, + "example": { + "query": { + "predicate": "enterprise_12345678:book:purchasePrice >= :price AND box:item:name = :name", + "params": { + "price": 100, + "name": "The Hobbit" + }, + "ancestors": [ + { + "id": "789", + "type": "folder" + } + ] + }, + "order_by": [ + { + "field_key": "enterprise_12345678:book:purchasePrice", + "direction": "asc" + } + ], + "limit": 1, + "fields": [ + "box:item:name", + "enterprise_12345678:book" + ] + }, + "additionalProperties": false, + "required": [ + "query" + ], + "title": "Query request body", + "x-box-tag": "query" + }, + "QueryResultEntry": { + "description": "A single item matching the query. Always includes the item `type` and `id`.\nIf a `fields` parameter was specified in the request, then additional item\nand/or metadata fields will be provided.", + "type": "object", + "properties": { + "id": { + "description": "The unique identifier of the matching item.", + "type": "string", + "example": "12345" + }, + "type": { + "description": "The type of the matching item.", + "type": "string", + "example": "file" + } + }, + "additionalProperties": {}, + "required": [ + "id", + "type" + ], + "title": "Query result entry", + "x-box-resource-id": "query_result_entry_v2026.0", + "x-box-tag": "query" + }, + "QueryResults": { + "description": "A paginated list of items matching the query, using milestone-based marker\npagination.", + "type": "object", + "properties": { + "entries": { + "description": "The list of items matching the query predicate.", + "type": "array", + "items": { + "$ref": "#/components/schemas/QueryResultEntry" + } + }, + "next_marker": { + "description": "The marker for the start of the next page of results. When `null`, there\nare no further results available.", + "type": "string", + "example": "xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA=", + "nullable": true + }, + "limit": { + "description": "The limit that was used for this request. This will be the same as the limit query \nparameter unless that value exceeded the maximum value allowed.", + "type": "integer", + "format": "int32", + "example": 50 + } + }, + "example": { + "entries": [ + { + "id": "12345", + "type": "file", + "box": { + "item": { + "name": "My Form" + } + }, + "enterprise_12345678": { + "book": { + "$parent": "file_12345", + "$scope": "enterprise_12345678", + "$template": "book", + "$version": 4, + "isbn": "1871263670", + "purchasePrice": 234.57, + "publicationYear": "1937" + } + } + } + ], + "next_marker": "xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA=", + "limit": 1 + }, + "additionalProperties": false, + "required": [ + "entries", + "next_marker", + "limit" + ], + "title": "Query results", + "x-box-resource-id": "query_results_v2026.0", + "x-box-tag": "query" + }, "User--Base": { "description": "A mini representation of a user, used when\nnested within another resource.", "type": "object", @@ -728,6 +1519,11 @@ "name": "Convert to Box note", "description": "Create Box Notes from supported source content (for example Markdown).", "x-box-tag": "notes" + }, + { + "name": "Query", + "description": "Query for your items.", + "x-box-tag": "query" } ], "externalDocs": { diff --git a/openapi/openapi.json b/openapi/openapi.json index b0408a55..85f5d08f 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -14,7 +14,7 @@ "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "2024.0", - "x-box-commit-hash": "5a03ed238f" + "x-box-commit-hash": "92c221bf9d" }, "servers": [ { @@ -31889,6 +31889,49 @@ "type": "boolean", "example": true, "nullable": false + }, + "collections": { + "description": "The collections that this file belongs to.\n\nFor more information, see the\n[collections guide](https://developer.box.com/guides/collections).", + "type": "array", + "items": { + "$ref": "#/components/schemas/Collection" + } + }, + "is_download_available": { + "description": "Whether the file's binary content is eligible to be downloaded.\n\nThis is a content-level flag and does not reflect whether the\ncurrent user is authorized to download the file. Use\n`permissions.can_download`, when available, for that.", + "type": "boolean", + "example": true + }, + "download_url": { + "description": "A pre-authorized, expiring URL for directly downloading the file's\ncontent. Requires authentication and is valid only for the current\nsession.\n\nThis field is only returned for files, not folders or web links.", + "type": "string", + "format": "url", + "example": "https://dl.boxcloud.com/d/1/example_token/download" + }, + "authenticated_download_url": { + "description": "A stable API URL for the file content endpoint,\n`/2.0/files/{id}/content`. Unlike `download_url`, authorization is\nevaluated when the URL is requested with a valid access token.\n\nThis field is only returned for files, not folders or web links.", + "type": "string", + "format": "url", + "example": "https://api.box.com/2.0/files/12345/content" + }, + "allowed_shared_link_access_levels": { + "description": "The shared link access levels the authenticated user is allowed to\nuse when creating or updating a shared link for this file.\n\nThe list depends on item policy and user authorization, so it may be\nnarrower than the levels available to the owner. An empty array means\nno access level is available to this user.", + "type": "array", + "items": { + "title": "Shared link access level", + "type": "string", + "description": "The access level for a shared link.", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ] + }, + "example": [ + "open" + ], + "nullable": false } } } @@ -33394,10 +33437,13 @@ ] }, "allowed_shared_link_access_levels": { - "description": "A list of access levels that are available\nfor this folder.\n\nFor some folders, like the root folder, this will always\nbe an empty list as sharing is not allowed at that level.", + "description": "The shared link access levels the authenticated user is allowed to\nuse when creating or updating a shared link for this folder.\n\nThe list depends on item policy and user authorization. For some\nfolders, like the root folder, this is always empty as sharing is\nnot allowed at that level.", "type": "array", "items": { + "title": "Shared link access level", "type": "string", + "description": "The access level for a shared link.", + "example": "open", "enum": [ "open", "company", @@ -33509,6 +33555,13 @@ "type": "boolean", "example": true, "nullable": false + }, + "collections": { + "description": "The collections that this folder belongs to.\n\nFor more information, see the\n[collections guide](https://developer.box.com/guides/collections).", + "type": "array", + "items": { + "$ref": "#/components/schemas/Collection" + } } } } @@ -43355,6 +43408,32 @@ "trashed", "deleted" ] + }, + "collections": { + "description": "The collections that this web link belongs to.\n\nFor more information, see the\n[collections guide](https://developer.box.com/guides/collections).", + "type": "array", + "items": { + "$ref": "#/components/schemas/Collection" + } + }, + "allowed_shared_link_access_levels": { + "description": "The shared link access levels the authenticated user is allowed to\nuse when creating or updating a shared link for this web link.\n\nThe list depends on item policy and user authorization, so it may be\nnarrower than the levels available to the owner. An empty array means\nno access level is available to this user.", + "type": "array", + "items": { + "title": "Shared link access level", + "type": "string", + "description": "The access level for a shared link.", + "example": "open", + "enum": [ + "open", + "company", + "collaborators" + ] + }, + "example": [ + "open" + ], + "nullable": false } } }