{ "openapi": "3.0.2", "info": { "title": "Box Platform API", "description": "[Box Platform](https://developer.box.com) provides functionality to provide access to content stored within [Box](https://box.com). It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies.", "termsOfService": "https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9", "contact": { "name": "Box, Inc", "url": "https://developer.box.com", "email": "devrel@box.com" }, "license": { "name": "Apache-2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "2026.0", "x-box-commit-hash": "21e370b9bd" }, "servers": [ { "url": "https://api.box.com/2.0", "description": "Box Platform API server." } ], "paths": { "/automate_workflows": { "get": { "operationId": "get_automate_workflows_v2026.0", "summary": "List Automate workflows defined as callable actions", "description": "Returns workflow actions from Automate for a folder, using the `WORKFLOW` action category.", "x-stability-level": "beta", "parameters": [ { "name": "folder_id", "in": "query", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "$ref": "#/components/parameters/BoxVersionHeader" } ], "responses": { "200": { "description": "Returns workflow actions that can be manually started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomateWorkflows" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "automate_workflows", "tags": [ "Automate Workflows" ], "x-box-unsupported-on-free-developer": true, "x-codeSamples": [ { "lang": "curl", "label": "List Automate workflows defined as callable actions", "source": "curl -i -X GET \"https://api.box.com/2.0/automate_workflows?folder_id=12345\" \\\n -H \"box-version: 2026.0\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List Automate workflows defined as callable actions", "source": "await adminClient.AutomateWorkflows.GetAutomateWorkflowsV2026R0Async(queryParams: new GetAutomateWorkflowsV2026R0QueryParams(folderId: workflowFolderId));" }, { "lang": "swift", "label": "List Automate workflows defined as callable actions", "source": "try await adminClient.automateWorkflows.getAutomateWorkflowsV2026R0(queryParams: GetAutomateWorkflowsV2026R0QueryParams(folderId: workflowFolderId))" }, { "lang": "java", "label": "List Automate workflows defined as callable actions", "source": "adminClient.getAutomateWorkflows().getAutomateWorkflowsV2026R0(new GetAutomateWorkflowsV2026R0QueryParams(workflowFolderId))" }, { "lang": "node", "label": "List Automate workflows defined as callable actions", "source": "await adminClient.automateWorkflows.getAutomateWorkflowsV2026R0({\n folderId: workflowFolderId,\n} satisfies GetAutomateWorkflowsV2026R0QueryParams);" }, { "lang": "python", "label": "List Automate workflows defined as callable actions", "source": "admin_client.automate_workflows.get_automate_workflows_v2026_r0(workflow_folder_id)" } ] } }, "/automate_workflows/{workflow_id}/start": { "post": { "operationId": "post_automate_workflows_id_start_v2026.0", "summary": "Start Automate workflow", "description": "Starts an Automate workflow manually by using a workflow action ID and file IDs.", "x-stability-level": "beta", "parameters": [ { "name": "workflow_id", "in": "path", "description": "The ID of the workflow.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "$ref": "#/components/parameters/BoxVersionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomateWorkflowStartRequest" } } } }, "responses": { "204": { "description": "Starts the workflow." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "automate_workflows", "tags": [ "Automate Workflows" ], "x-box-unsupported-on-free-developer": true, "x-codeSamples": [ { "lang": "curl", "label": "Start Automate workflow", "source": "curl -i -X POST \"https://api.box.com/2.0/automate_workflows/12345/start\" \\\n -H \"box-version: 2026.0\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"workflow_action_id\": \"981\",\n \"file_ids\": [\"123\"]\n }'" }, { "lang": "dotnet", "label": "Start Automate workflow", "source": "await adminClient.AutomateWorkflows.CreateAutomateWorkflowStartV2026R0Async(workflowId: workflowAction.Workflow.Id, requestBody: new AutomateWorkflowStartRequestV2026R0(workflowActionId: workflowAction.Id, fileIds: Array.AsReadOnly(new [] {workflowFileId})));" }, { "lang": "swift", "label": "Start Automate workflow", "source": "try await adminClient.automateWorkflows.createAutomateWorkflowStartV2026R0(workflowId: workflowAction.workflow.id, requestBody: AutomateWorkflowStartRequestV2026R0(workflowActionId: workflowAction.id, fileIds: [workflowFileId]))" }, { "lang": "java", "label": "Start Automate workflow", "source": "adminClient.getAutomateWorkflows().createAutomateWorkflowStartV2026R0(workflowAction.getWorkflow().getId(), new AutomateWorkflowStartRequestV2026R0(workflowAction.getId(), Arrays.asList(workflowFileId)))" }, { "lang": "node", "label": "Start Automate workflow", "source": "await adminClient.automateWorkflows.createAutomateWorkflowStartV2026R0(\n workflowAction.workflow.id,\n {\n workflowActionId: workflowAction.id,\n fileIds: [workflowFileId],\n } satisfies AutomateWorkflowStartRequestV2026R0,\n);" }, { "lang": "python", "label": "Start Automate workflow", "source": "admin_client.automate_workflows.create_automate_workflow_start_v2026_r0(\n workflow_action.workflow.id, workflow_action.id, [workflow_file_id]\n)" } ] } }, "/notes/convert": { "post": { "operationId": "post_notes_convert_v2026.0", "summary": "Convert content to Box Note", "description": "Creates a Box Note (`.boxnote` file) from supported source content. See the `content_format` field for supported formats.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesConvertRequestBody" } } } }, "responses": { "201": { "description": "The note was created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesConvertResponse" } } } }, "400": { "description": "Returned when the request body is malformed, fails schema validation, or required fields are missing. A missing or unknown parent folder is not indicated with this status (see `404`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the authenticated user does not have permission to create a file in the parent folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the parent folder does not exist, or the user does not have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returned when a preflight check fails (for example, a name conflict).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "413": { "description": "Returned when the request payload is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "422": { "description": "Returned when the content could not be converted to a note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returned when an unexpected server error occurs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "501": { "description": "Returned when this operation is not implemented or not yet available on the server (for example, while routing to the Notes service is still being enabled).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "Returned when an unexpected client error occurs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "notes", "tags": [ "Convert to Box note" ], "x-codeSamples": [ { "lang": "dotnet", "label": "Convert content to Box Note", "source": "await client.Notes.CreateNoteConvertV2026R0Async(requestBody: new NotesConvertRequestBodyV2026R0(content: markdownContent, contentFormat: NotesConvertRequestBodyV2026R0ContentFormatField.Markdown, parent: new FolderReferenceV2026R0(id: \"0\"), name: noteName));" }, { "lang": "swift", "label": "Convert content to Box Note", "source": "try await client.notes.createNoteConvertV2026R0(requestBody: NotesConvertRequestBodyV2026R0(content: markdownContent, contentFormat: NotesConvertRequestBodyV2026R0ContentFormatField.markdown, parent: FolderReferenceV2026R0(id: \"0\"), name: noteName))" }, { "lang": "java", "label": "Convert content to Box Note", "source": "client.getNotes().createNoteConvertV2026R0(new NotesConvertRequestBodyV2026R0.Builder(markdownContent, new FolderReferenceV2026R0(\"0\"), noteName).contentFormat(NotesConvertRequestBodyV2026R0ContentFormatField.MARKDOWN).build())" }, { "lang": "node", "label": "Convert content to Box Note", "source": "await client.notes.createNoteConvertV2026R0({\n content: markdownContent,\n contentFormat: 'markdown' as NotesConvertRequestBodyV2026R0ContentFormatField,\n parent: new FolderReferenceV2026R0({ id: '0' }),\n name: noteName,\n} satisfies NotesConvertRequestBodyV2026R0Input);" }, { "lang": "python", "label": "Convert content to Box Note", "source": "client.notes.create_note_convert_v2026_r0(\n markdown_content,\n FolderReferenceV2026R0(id=\"0\"),\n note_name,\n content_format=CreateNoteConvertV2026R0ContentFormat.MARKDOWN,\n)" } ] } }, "/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 across item fields and metadata templates. Results can be sorted, paginated, and 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 validation, a referenced scope is not valid, 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 missing, 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 items, 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 user 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" ], "x-codeSamples": [ { "lang": "dotnet", "label": "Query for Box items", "source": "await client.Query.CreateQueryV2026R0Async(requestBody: new QueryRequestBodyV2026R0(query: new QueryRequestBodyV2026R0QueryField(predicate: predicate) { Parameters = new Dictionary() { { \"name\", \"John\" }, { \"age\", 50 } }, Ancestors = Array.AsReadOnly(new [] {new QueryAncestorReferenceV2026R0(id: \"0\", type: \"folder\")}) }) { Limit = 10, Fields = Array.AsReadOnly(new [] {\"box:item:name\",searchFrom}) });" }, { "lang": "swift", "label": "Query for Box items", "source": "try await client.query.createQueryV2026R0(requestBody: QueryRequestBodyV2026R0(query: QueryRequestBodyV2026R0QueryField(predicate: predicate, params: [\"name\": \"John\", \"age\": 50], ancestors: [QueryAncestorReferenceV2026R0(id: \"0\", type: \"folder\")]), limit: 10, fields: [\"box:item:name\", searchFrom]))" }, { "lang": "java", "label": "Query for Box items", "source": "client.getQuery().createQueryV2026R0(new QueryRequestBodyV2026R0.Builder(new QueryRequestBodyV2026R0QueryField.Builder(predicate).params(mapOf(entryOf(\"name\", \"John\"), entryOf(\"age\", 50))).ancestors(Arrays.asList(new QueryAncestorReferenceV2026R0(\"0\", \"folder\"))).build()).limit(10).fields(Arrays.asList(\"box:item:name\", searchFrom)).build())" }, { "lang": "node", "label": "Query for Box items", "source": "await client.query.createQueryV2026R0({\n query: {\n predicate: predicate,\n params: { ['name']: 'John', ['age']: 50 },\n ancestors: [\n { id: '0', type: 'folder' } satisfies QueryAncestorReferenceV2026R0,\n ],\n } satisfies QueryRequestBodyV2026R0QueryField,\n limit: 10,\n fields: ['box:item:name', searchFrom],\n} satisfies QueryRequestBodyV2026R0);" }, { "lang": "python", "label": "Query for Box items", "source": "client.query.create_query_v2026_r0(\n CreateQueryV2026R0Query(\n predicate=predicate,\n params={\"name\": \"John\", \"age\": 50},\n ancestors=[QueryAncestorReferenceV2026R0(id=\"0\", type=\"folder\")],\n ),\n limit=10,\n fields=[\"box:item:name\", search_from],\n)" } ] } }, "/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. Filters are applied first, followed by optional grouping, after which the requested metrics (such as `sum`, `avg`, `min`, `max`, and `count`) are computed 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 validation, 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 missing, 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 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 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" ], "x-codeSamples": [ { "lang": "dotnet", "label": "Create insights for Box items", "source": "await client.Query.CreateQueryInsightV2026R0Async(requestBody: new QueryInsightsRequestBodyV2026R0(query: new QueryInsightsRequestBodyV2026R0QueryField(predicate: predicate) { Parameters = new Dictionary() { { \"minAmount\", 0 } }, Ancestors = Array.AsReadOnly(new [] {new QueryAncestorReferenceV2026R0(id: \"0\", type: \"folder\")}), GroupBy = Array.AsReadOnly(new [] {new QueryInsightsGroupByV2026R0(field: string.Concat(mdPrefix, \".category\")) { BucketLimit = 5 }}) }, metrics: metrics));" }, { "lang": "swift", "label": "Create insights for Box items", "source": "try await client.query.createQueryInsightV2026R0(requestBody: QueryInsightsRequestBodyV2026R0(query: QueryInsightsRequestBodyV2026R0QueryField(predicate: predicate, params: [\"minAmount\": 0], ancestors: [QueryAncestorReferenceV2026R0(id: \"0\", type: \"folder\")], groupBy: [QueryInsightsGroupByV2026R0(field: \"\\(mdPrefix)\\(\".category\")\", bucketLimit: 5)]), metrics: metrics))" }, { "lang": "java", "label": "Create insights for Box items", "source": "client.getQuery().createQueryInsightV2026R0(new QueryInsightsRequestBodyV2026R0(new QueryInsightsRequestBodyV2026R0QueryField.Builder(predicate).params(mapOf(entryOf(\"minAmount\", 0))).ancestors(Arrays.asList(new QueryAncestorReferenceV2026R0(\"0\", \"folder\"))).groupBy(Arrays.asList(new QueryInsightsGroupByV2026R0.Builder(String.join(\"\", mdPrefix, \".category\")).bucketLimit(5).build())).build(), metrics))" }, { "lang": "node", "label": "Create insights for Box items", "source": "await client.query.createQueryInsightV2026R0({\n query: {\n predicate: predicate,\n params: { ['minAmount']: 0 },\n ancestors: [\n { id: '0', type: 'folder' } satisfies QueryAncestorReferenceV2026R0,\n ],\n groupBy: [\n {\n field: ''.concat(mdPrefix, '.category') as string,\n bucketLimit: 5,\n } satisfies QueryInsightsGroupByV2026R0,\n ],\n } satisfies QueryInsightsRequestBodyV2026R0QueryField,\n metrics: metrics,\n} satisfies QueryInsightsRequestBodyV2026R0);" }, { "lang": "python", "label": "Create insights for Box items", "source": "client.query.create_query_insight_v2026_r0(\n CreateQueryInsightV2026R0Query(\n predicate=predicate,\n params={\"minAmount\": 0},\n ancestors=[QueryAncestorReferenceV2026R0(id=\"0\", type=\"folder\")],\n group_by=[\n QueryInsightsGroupByV2026R0(\n field=\"\".join([md_prefix, \".category\"]), bucket_limit=5\n )\n ],\n ),\n metrics,\n)" } ] } } }, "components": { "parameters": { "BoxVersionHeader": { "name": "box-version", "in": "header", "description": "Version header.", "allowEmptyValue": false, "required": true, "schema": { "type": "string", "enum": [ "2026.0" ] }, "example": "2026.0" } }, "schemas": { "AutomateWorkflowAction": { "description": "An Automate action that can start a workflow.", "type": "object", "properties": { "id": { "description": "The identifier for the Automate action.", "type": "string", "example": "981" }, "type": { "description": "The object type for this workflow action wrapper.", "type": "string", "example": "workflow_action", "enum": [ "workflow_action" ] }, "action_type": { "description": "The type that defines the behavior of this action.", "type": "string", "example": "run_workflow", "enum": [ "run_workflow" ] }, "description": { "description": "A human-readable description of the workflow action.", "type": "string", "example": "Runs workflow execution for selected files" }, "created_at": { "description": "The date and time when the action was created.", "type": "string", "format": "date-time", "example": "2026-04-01T10:00:00.000Z" }, "updated_at": { "description": "The date and time when the action was last updated.", "type": "string", "format": "date-time", "example": "2026-04-02T11:00:00.000Z" }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user that created the action." } ] }, "updated_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user that last updated the action." } ] }, "workflow": { "$ref": "#/components/schemas/AutomateWorkflowReference" } }, "required": [ "id", "type", "action_type", "workflow" ], "title": "Automate Workflow Action" }, "AutomateWorkflowReference": { "description": "A reference to an Automate workflow.", "type": "object", "properties": { "id": { "description": "The identifier for the Automate workflow instance.", "type": "string", "example": "545" }, "type": { "description": "The object type.", "type": "string", "example": "workflow", "enum": [ "workflow" ] }, "name": { "description": "The display name for the Automate workflow.", "type": "string", "example": "Contract approval workflow" } }, "required": [ "id", "type" ], "title": "Automate Workflow Reference" }, "AutomateWorkflows": { "description": "A list of Automate workflow actions.", "allOf": [ { "properties": { "entries": { "description": "Workflow actions available for manual start.", "type": "array", "items": { "$ref": "#/components/schemas/AutomateWorkflowAction" } } } }, { "type": "object", "description": "The part of an API response that describes marker based pagination.", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } } } ], "title": "Automate Workflow Actions", "x-box-resource-id": "automate_workflows_v2026.0" }, "AutomateWorkflowStartRequest": { "description": "Request body to start an Automate workflow.", "type": "object", "properties": { "workflow_action_id": { "description": "The callable action ID used to trigger the selected workflow.", "type": "string", "example": "981" }, "file_ids": { "description": "The files to process with the selected workflow.", "type": "array", "items": { "type": "string", "example": "123" }, "example": [ "123" ], "minItems": 1 } }, "required": [ "workflow_action_id", "file_ids" ], "title": "Automate Workflow Start Request" }, "ClientError": { "description": "A generic error.", "type": "object", "properties": { "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 about the error. The possible fields are defined on a 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 when contacting Box support.", "type": "string", "example": "abcdef123456", "nullable": false } }, "title": "Client error", "x-box-resource-id": "client_error_v2026.0" }, "FolderReference": { "description": "Folder reference.", "type": "object", "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" } }, "required": [ "type", "id" ], "title": "Folder reference" }, "NotesConvertRequestBody": { "description": "Request body for converting source content into a Box Note file.", "type": "object", "properties": { "content": { "description": "The content to convert to a note. See the `content_format` field for supported formats.", "example": "# My note\\n\\nHello from Markdown.", "maxLength": 1048576, "type": "string" }, "content_format": { "description": "Format of the content to convert.", "type": "string", "example": "markdown", "enum": [ "markdown" ] }, "parent": { "$ref": "#/components/schemas/FolderReference" }, "name": { "description": "The name for the created note. The `.boxnote` extension is appended automatically.", "type": "string", "example": "Quarterly plan", "maxLength": 247, "minLength": 1 } }, "additionalProperties": false, "required": [ "content", "content_format", "parent", "name" ], "title": "Notes convert request body", "x-box-tag": "notes" }, "NotesConvertResponse": { "description": "Identifies the created Box Note file.", "type": "object", "properties": { "type": { "description": "The Box resource type; always `file` for a Box file.", "type": "string", "example": "file", "enum": [ "file" ] }, "id": { "description": "Box file ID of the created `.boxnote` file.", "type": "string", "example": "1234567890" } }, "additionalProperties": false, "required": [ "type", "id" ], "title": "Notes convert response", "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 entity 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) and the computed metrics.", "type": "object", "properties": { "key": { "description": "The grouping key values associated with the entry. Contains one value per `group_by` field for `group` entries, and is empty for `overall` and `other` entries.", "type": "array", "items": { "type": "string", "example": "ContractType1" }, "example": [ "ContractType1" ] }, "type": { "description": "The type of insight entry, indicating how the associated metrics are aggregated.", "type": "string", "example": "group", "enum": [ "group", "overall", "other" ] }, "metrics": { "description": "A map of metric aliases to their computed results. For `other` entries, the count 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 computed 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 `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, the 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 single grouping field is supported.", "type": "object", "properties": { "field": { "description": "The fully qualified field name to group by. Supports metadata and item properties.", "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 field 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 computation.", "type": "object", "properties": { "query": { "description": "The filtering and grouping definition. Filters are applied first, followed by grouping, before metrics are computed.", "type": "object", "additionalProperties": false, "properties": { "predicate": { "description": "A logical expression used to filter the dataset prior to metric computation, similar to an SQL `WHERE` clause. May include named 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. Required only when the predicate contains parameter placeholders. The type 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 ancestors. The user must have access to every listed ancestor. When omitted, 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 single 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 metrics may be defined. Each alias must be a unique, non-empty string of up to 256 characters, containing only letters, digits, `_`, `-`, or `.`, and must not start with a digit, `_`, `-`, or `.`. May be empty to request only 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 are 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, optional 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 parameters and ancestor restrictions.", "type": "object", "additionalProperties": false, "properties": { "predicate": { "description": "A logical expression used to filter the dataset, similar to an SQL `WHERE` clause. May include named parameters referenced as `: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. Required only when the predicate contains parameter placeholders. The type 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 recursive descendants. The user must have read access to every listed ancestor.", "type": "array", "items": { "$ref": "#/components/schemas/QueryAncestorReference" } } }, "required": [ "predicate" ] }, "order_by": { "description": "The sorting criteria for the result set. Entries are applied sequentially to 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 provided.", "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 value must be one of: a fully qualified item field key (for example `box:item:name`), a metadata template key to hydrate the full template (for example `enterprise_12345678:project`), or a specific metadata template field key to hydrate a single field from the template (for example `enterprise_12345678:project:name`). When omitted, entries include only the item 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 retrieval. When provided, all other request parameters must exactly match those 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`. If a `fields` parameter was specified in the request, then additional item and/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 pagination.", "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 are 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 parameter 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 nested within another resource.", "type": "object", "properties": { "id": { "description": "The unique identifier for this user.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `user`.", "type": "string", "example": "user", "enum": [ "user" ], "nullable": false } }, "required": [ "type", "id" ], "title": "User (Base)" }, "User--Mini": { "description": "A mini representation of a user, as can be returned when nested within other resources.", "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": { "OAuth2Security": { "type": "oauth2", "description": "The access token received from the authorization server in the OAuth 2.0 flow.", "flows": { "authorizationCode": { "authorizationUrl": "https://account.box.com/api/oauth2/authorize", "tokenUrl": "https://api.box.com/oauth2/token", "scopes": { "root_readonly": "Read all files and folders stored in Box", "root_readwrite": "Read and write all files and folders stored in Box", "manage_app_users": "Provision and manage app users", "manage_managed_users": "Provision and manage managed users", "manage_groups": "Manage an enterprise's groups", "manage_webhook": "Create webhooks programmatically through the API", "manage_enterprise_properties": "Manage enterprise properties", "manage_data_retention": "Manage data retention polices", "manage_legal_hold": "Manage Legal Holds" } } } } } }, "security": [ { "OAuth2Security": [] } ], "tags": [ { "name": "Automate Workflows", "description": "Endpoints for listing and manually starting Automate workflow actions.", "x-box-tag": "automate_workflows" }, { "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": { "description": "Box Developer Documentation.", "url": "https://developer.box.com" }, "x-mint": { "mcp": { "enabled": true } } }