openapi-v2026.0.json

{
  "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": "e1aaef784a"
  },
  "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\n`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\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.",
            "required": true,
            "schema": {
              "type": "string",
              "nullable": false
            },
            "example": "12345"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "The maximum number of items to return per page.",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int64",
              "maximum": 1000
            },
            "example": 1000
          },
          {
            "name": "marker",
            "in": "query",
            "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.",
            "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
      }
    },
    "/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
      }
    },
    "/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\nrequired fields are missing. A missing or unknown parent folder is not\nindicated 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\nis 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\na 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\naccess 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\nthe server (for example, while routing to the Notes service is still being\nenabled).",
            "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"
        ]
      }
    },
    "/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": {
    "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\nbased pagination.",
            "properties": {
              "limit": {
                "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.",
                "type": "integer",
                "format": "int64",
                "example": 1000
              },
              "next_marker": {
                "description": "The marker for the start of the next page of results.",
                "type": "string",
                "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
                "nullable": true
              }
            }
          }
        ],
        "title": "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\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_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\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",
        "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\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": {
      "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"
  }
}