{ "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": "e34422e289" }, "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" ] } }, "/document_splits": { "post": { "operationId": "post_document_splits_v2026.0", "summary": "Create Document Split job", "description": "Initiates a Document Split job for the supplied source file. The job runs\nasynchronously; clients can poll the returned job ID to track progress.\n\nAll split-specific input lives under `split_input`. When\n`split_input.split_type` is `manual`, provide\n`split_input.split_definition` (continuous page ranges; `version` may be\nomitted or `v_1`). When `split_input.split_type` is `page_selection`,\nprovide `split_input.page_selection` (non-linear page segments; `version`\nmay be omitted or `v_2`). `split_input.prompt` must not be provided for\neither of those variants. When `split_input.split_type` is `smart`,\n`split_input.prompt` is required and neither\n`split_input.split_definition` nor `split_input.page_selection` must be\nprovided.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSplitCreateRequest" }, "examples": { "manual": { "summary": "Manual split request", "value": { "source_file_id": "12345", "destination_folder_id": "14047816008", "input_source": "api", "split_input": { "split_type": "manual", "split_definition": [ { "start": 1, "end": 5 }, { "start": 6, "end": 14 } ] } } }, "page_selection": { "summary": "Page selection split request", "value": { "source_file_id": "12345", "destination_folder_id": "14047816008", "input_source": "api", "split_input": { "split_type": "page_selection", "version": "v_2", "page_selection": [ { "name": "exhibits", "segments": [ { "type": "single_page", "page": 4 }, { "type": "single_page", "page": 8 }, { "type": "single_page", "page": 12 } ] }, { "name": "signatures", "segments": [ { "type": "page_range", "start": 6, "end": 8 }, { "type": "single_page", "page": 15 } ] } ] } } }, "smart": { "summary": "Smart split request", "value": { "source_file_id": "12345", "destination_folder_id": "14047816008", "input_source": "api", "split_input": { "split_type": "smart", "prompt": "Split this contract into one file per signed section." } } } } } } }, "responses": { "202": { "description": "The Document Split job was accepted for processing. Returns a reference\nto the newly created job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSplitCreateResponse" } } } }, "400": { "description": "Returned when the request body is malformed or required fields are\nmissing.", "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 access to the\nDocument Generation feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the source file or destination folder cannot be found\nor the user does not have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "document_split", "tags": [ "Document Split" ] }, "get": { "operationId": "get_document_splits_v2026.0", "summary": "List Document Split jobs", "description": "Returns a paginated list of Document Split jobs accessible to the\nauthenticated user.", "parameters": [ { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "$ref": "#/components/parameters/BoxVersionHeader" } ], "responses": { "200": { "description": "Returns a paginated list of Document Split jobs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSplits" } } } }, "400": { "description": "Returned when the user has passed in a malformed `marker` or `limit`\nvalue.", "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 access to the\nDocument Generation feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "document_split", "tags": [ "Document Split" ] } }, "/document_splits/{document_split_id}": { "get": { "operationId": "get_document_splits_id_v2026.0", "summary": "Get Document Split job by ID", "description": "Returns details for a single Document Split job identified by its ID,\nincluding the current status, the input definition, and any output files\nproduced by the job.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "document_split_id", "in": "path", "description": "The unique identifier for the Document Split job.", "required": true, "schema": { "type": "string" }, "example": "1748426" } ], "responses": { "200": { "description": "Returns the Document Split job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSplit" } } } }, "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 access to the\nDocument Generation feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the Document Split job is not found or the user does not\nhave access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "document_split", "tags": [ "Document Split" ] } }, "/query": { "post": { "operationId": "post_query_v2026.0", "summary": "Box Query", "description": "Runs a query to discover Box items using a logical predicate, similar to a SQL\nWHERE clause. The predicate can filter across multiple metadata templates and\nitem fields in a single request. Results can be sorted, paginated with markers,\nand shaped with fields so each entry includes additional item or metadata\nattributes.\n\nThis is the item-retrieval endpoint in the Query API (version 2026.0). Unlike\nthe [Metadata Query API](https://developer.box.com/reference/post-metadata-queries-execute-read),\nit is not limited to a single metadata template or to files and folders. For\ntotals and grouped metrics over the same predicates, use\n[Query Insights](https://developer.box.com/reference/v2026.0/post-query-insights)\ninstead of paging through every matching item.\n\nFor predicate syntax, parameters, examples, pagination behavior, and error\ncodes, see the\n[Box Query guide](https://developer.box.com/guides/query/box-query). For shared\nresponse schemas, including Query results and result entries, see\n[Query resources](https://developer.box.com/reference/v2026.0/query-resources).", "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" ] } }, "/shuttle_systems": { "get": { "operationId": "get_shuttle_systems_v2026.0", "summary": "List shuttle systems", "description": "Returns a paginated list of shuttle systems accessible to the\nauthenticated user.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of shuttle systems.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleSystems" } } } }, "400": { "description": "Returned when the user has passed in a malformed `marker` or `limit`\nvalue.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "post": { "operationId": "post_shuttle_systems_v2026.0", "summary": "Create shuttle system", "description": "Creates a new shuttle system. Only Windows agent systems can be created\nthrough the public API; other system types must be configured through the\nShuttle application.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleSystemCreateRequest" }, "examples": { "windows": { "summary": "Create a Windows agent system", "value": { "name": "NYC File Server", "system_type": "windows" } } } } } }, "responses": { "201": { "description": "Returns the newly created shuttle system.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleSystem" } } } }, "400": { "description": "Returned when the request body is malformed or required fields are\nmissing.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_systems/{shuttle_system_id}": { "get": { "operationId": "get_shuttle_systems_id_v2026.0", "summary": "Get shuttle system by ID", "description": "Returns details for a single shuttle system identified by its ID,\nincluding its type and connection state.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_system_id", "in": "path", "description": "The unique identifier for the shuttle system.", "required": true, "schema": { "type": "string" }, "example": "6a315c0754833bfc5df067bf" } ], "responses": { "200": { "description": "Returns the shuttle system.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleSystem" } } } }, "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle system is not found or the user does not\nhave access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "put": { "operationId": "put_shuttle_systems_id_v2026.0", "summary": "Update shuttle system", "description": "Updates the mutable properties of an existing shuttle system identified by\nits ID. Only the fields supplied in the request body are changed.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_system_id", "in": "path", "description": "The unique identifier for the shuttle system.", "required": true, "schema": { "type": "string" }, "example": "6a315c0754833bfc5df067bf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleSystemUpdateRequest" }, "examples": { "rename": { "summary": "Rename a shuttle system", "value": { "name": "NYC File Server (Primary)" } } } } } }, "responses": { "200": { "description": "Returns the updated shuttle system.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleSystem" } } } }, "400": { "description": "Returned when the request body is malformed, empty, or fails\nvalidation.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle system is not found or the user does not\nhave access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "delete": { "operationId": "delete_shuttle_systems_id_v2026.0", "summary": "Delete shuttle system", "description": "Permanently deletes the shuttle system identified by its ID. This does not\naffect content that has already been migrated.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_system_id", "in": "path", "description": "The unique identifier for the shuttle system.", "required": true, "schema": { "type": "string" }, "example": "6a315c0754833bfc5df067bf" } ], "responses": { "204": { "description": "Returns an empty response when the shuttle system was successfully\ndeleted." }, "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle system is not found or the user does not\nhave access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_systems/{shuttle_system_id}/issue_registration_token": { "post": { "operationId": "post_shuttle_systems_id_issue_registration_token_v2026.0", "summary": "Issue registration token for Windows system", "description": "Issues a new installation token for the Windows shuttle system identified\nby its ID. Paste the returned token into the Windows agent installer to\nregister the agent with this system.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_system_id", "in": "path", "description": "The unique identifier for the shuttle system.", "required": true, "schema": { "type": "string" }, "example": "6a315c0754833bfc5df067bf" } ], "responses": { "200": { "description": "Returns the agent installation credentials for the Windows system.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleAgentCredentials" } } } }, "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle system is not found or the user does not\nhave access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_jobs": { "get": { "operationId": "get_shuttle_jobs_v2026.0", "summary": "List shuttle jobs", "description": "Returns a paginated list of shuttle jobs accessible to the authenticated\nuser.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of shuttle jobs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleJobs" } } } }, "400": { "description": "Returned when the user has passed in a malformed `marker` or `limit`\nvalue.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "post": { "operationId": "post_shuttle_jobs_v2026.0", "summary": "Create shuttle job", "description": "Creates a new shuttle job that describes a migration from the given source\nsystem into Box.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleJobCreateRequest" }, "examples": { "transfer": { "summary": "Create a transfer job", "value": { "name": "Q4 SharePoint to Box", "job_type": "transfer", "source_system_id": "6a3ba68e810d9156194530a1" } } } } } }, "responses": { "201": { "description": "Returns the newly created shuttle job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleJob" } } } }, "400": { "description": "Returned when the request body is malformed or required fields are\nmissing.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the referenced source system cannot be found or the user\ndoes not have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_jobs/{shuttle_job_id}": { "get": { "operationId": "get_shuttle_jobs_id_v2026.0", "summary": "Get shuttle job by ID", "description": "Returns details for a single shuttle job identified by its ID, including\nits current state, mapping-preparation state, and configured source system.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_job_id", "in": "path", "description": "The unique identifier for the shuttle job.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1" } ], "responses": { "200": { "description": "Returns the shuttle job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleJob" } } } }, "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "put": { "operationId": "put_shuttle_jobs_id_v2026.0", "summary": "Update shuttle job", "description": "Updates the mutable properties of an existing shuttle job identified by its\nID. Only the fields supplied in the request body are changed.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_job_id", "in": "path", "description": "The unique identifier for the shuttle job.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleJobUpdateRequest" }, "examples": { "rename": { "summary": "Rename a shuttle job", "value": { "name": "Q4 SharePoint to Box (Primary)" } } } } } }, "responses": { "200": { "description": "Returns the updated shuttle job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleJob" } } } }, "400": { "description": "Returned when the request body is malformed, empty, or fails\nvalidation.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "delete": { "operationId": "delete_shuttle_jobs_id_v2026.0", "summary": "Delete shuttle job", "description": "Permanently deletes the shuttle job identified by its ID. This does not\naffect content that has already been migrated.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_job_id", "in": "path", "description": "The unique identifier for the shuttle job.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1" } ], "responses": { "204": { "description": "Returns an empty response when the shuttle job was successfully deleted." }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the authenticated user is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_jobs/{shuttle_job_id}/start": { "post": { "operationId": "post_shuttle_jobs_id_start_v2026.0", "summary": "Start shuttle job", "description": "Starts the job in the given mode. When no body is provided the job runs in\nsimulation mode.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_job_id", "in": "path", "description": "The unique identifier for the shuttle job.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleJobStartRequest" }, "examples": { "simulation": { "summary": "Start a simulation run", "value": { "mode": "simulation" } } } } } }, "responses": { "202": { "description": "The shuttle job was accepted and is being started." }, "400": { "description": "Returned when the request body is malformed or fails validation.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returned when the job is not ready or is in a state that does not allow\nstarting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_jobs/{shuttle_job_id}/stop": { "post": { "operationId": "post_shuttle_jobs_id_stop_v2026.0", "summary": "Stop shuttle job", "description": "Stops a running shuttle job identified by its ID. Any work already in\nprogress is allowed to finish before the job transitions to a stopped\nstate.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_job_id", "in": "path", "description": "The unique identifier for the shuttle job.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1" } ], "responses": { "202": { "description": "The shuttle job was accepted and is being stopped." }, "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returned when the job is not in a running state and cannot be stopped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_jobs/{shuttle_job_id}/prepare_migration": { "post": { "operationId": "post_shuttle_jobs_id_prepare_migration_v2026.0", "summary": "Prepare migration", "description": "Validates the configured account and path mappings before a transfer. Only\nrelevant when account mapping is enabled.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_job_id", "in": "path", "description": "The unique identifier for the shuttle job.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1" } ], "responses": { "202": { "description": "The migration preparation was accepted and is being processed." }, "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returned when the job is not in a state that allows migration\npreparation, or account mapping is not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_runs": { "get": { "operationId": "get_shuttle_runs_v2026.0", "summary": "List shuttle runs", "description": "Returns a paginated list of runs for the shuttle job identified by\n`job_id`.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "job_id", "in": "query", "description": "The unique identifier of the shuttle job whose runs to list.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of shuttle runs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleRuns" } } } }, "400": { "description": "Returned when `job_id` is missing or the user has passed in a malformed\n`marker` or `limit` value.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_runs/{shuttle_run_id}": { "get": { "operationId": "get_shuttle_runs_id_v2026.0", "summary": "Get shuttle run by ID", "description": "Returns details for a single shuttle run identified by its ID, including\nits mode, state, timing, and transfer statistics.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_run_id", "in": "path", "description": "The unique identifier for the shuttle run, in the form\n`{job_id}:{run_number}`.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1:42" } ], "responses": { "200": { "description": "Returns the shuttle run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleRun" } } } }, "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle run is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_job_schedules": { "get": { "operationId": "get_shuttle_job_schedules_v2026.0", "summary": "List shuttle job schedules", "description": "Returns a paginated list of schedules for the shuttle job identified by\n`job_id`.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "job_id", "in": "query", "description": "The unique identifier of the shuttle job whose schedules to list.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of shuttle job schedules.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleJobSchedules" } } } }, "400": { "description": "Returned when `job_id` is missing or the user has passed in a malformed\n`marker` or `limit` value.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "post": { "operationId": "post_shuttle_job_schedules_v2026.0", "summary": "Create shuttle job schedule", "description": "Creates a schedule that starts runs of the shuttle job identified by\n`job_id`. The schedule starts a run either at a wall-clock time or after\nanother job's run meets a condition. Schedules cannot start a run in\n`scan` mode.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleJobScheduleCreateRequest" }, "examples": { "by_time": { "summary": "Create a daily time-based schedule", "value": { "job_id": "6a3ba68e810d9156194530a1", "run_mode": "transfer", "state": "enabled", "description": "Nightly finance share replay.", "trigger": { "type": "by_time", "start_at": "2026-03-16T09:00:00", "time_zone": "America/Los_Angeles", "repeat": "daily" } } }, "by_job": { "summary": "Create a job-triggered schedule", "value": { "job_id": "6a3ba68e810d9156194530a1", "run_mode": "analysis", "trigger": { "type": "by_job", "triggered_by_job_id": "8d2ca68e810d9156194530c3", "last_run_condition": "on_success" } } } } } } }, "responses": { "201": { "description": "Returns the newly created shuttle job schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleJobSchedule" } } } }, "400": { "description": "Returned when the request body is malformed or required fields are\nmissing.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when a referenced shuttle job cannot be found or the user\ndoes not have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_job_schedules/{shuttle_job_schedule_id}": { "get": { "operationId": "get_shuttle_job_schedules_id_v2026.0", "summary": "Get shuttle job schedule", "description": "Retrieves the shuttle job schedule identified by its ID.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_job_schedule_id", "in": "path", "description": "The unique identifier for the shuttle job schedule.", "required": true, "schema": { "type": "string" }, "example": "7c1ba68e810d9156194530b2" } ], "responses": { "200": { "description": "Returns the shuttle job schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleJobSchedule" } } } }, "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job schedule is not found or the user does\nnot have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "put": { "operationId": "put_shuttle_job_schedules_id_v2026.0", "summary": "Update shuttle job schedule", "description": "Updates the mutable properties of an existing shuttle job schedule\nidentified by its ID. Only the fields supplied in the request body are\nchanged. The owning job cannot be changed.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_job_schedule_id", "in": "path", "description": "The unique identifier for the shuttle job schedule.", "required": true, "schema": { "type": "string" }, "example": "7c1ba68e810d9156194530b2" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleJobScheduleUpdateRequest" }, "examples": { "pause": { "summary": "Pause a schedule", "value": { "state": "paused" } }, "replace_trigger": { "summary": "Replace the trigger with a weekly time-based schedule", "value": { "trigger": { "type": "by_time", "start_at": "2026-03-16T09:00:00", "time_zone": "America/Los_Angeles", "repeat": "weekly" } } } } } } }, "responses": { "200": { "description": "Returns the updated shuttle job schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleJobSchedule" } } } }, "400": { "description": "Returned when the request body is malformed, empty, or fails\nvalidation.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job schedule is not found or the user does\nnot have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "delete": { "operationId": "delete_shuttle_job_schedules_id_v2026.0", "summary": "Delete shuttle job schedule", "description": "Permanently deletes the shuttle job schedule identified by its ID. This\ndoes not affect runs that have already started.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_job_schedule_id", "in": "path", "description": "The unique identifier for the shuttle job schedule.", "required": true, "schema": { "type": "string" }, "example": "7c1ba68e810d9156194530b2" } ], "responses": { "204": { "description": "Returns an empty response when the shuttle job schedule was\nsuccessfully deleted." }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the authenticated user is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job schedule is not found or the user does\nnot have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_path_mappings": { "get": { "operationId": "get_shuttle_path_mappings_v2026.0", "summary": "List shuttle path mappings", "description": "Returns a paginated list of path mappings for the shuttle job identified\nby `job_id`.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "job_id", "in": "query", "description": "The unique identifier of the shuttle job whose path mappings to list.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of shuttle path mappings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttlePathMappings" } } } }, "400": { "description": "Returned when `job_id` is missing or the user has passed in a malformed\n`marker` or `limit` value.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "post": { "operationId": "post_shuttle_path_mappings_v2026.0", "summary": "Create shuttle path mapping", "description": "Creates a path mapping that connects a source location on the migrated\nsystem to a destination in Box for the given shuttle job.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttlePathMappingCreateRequest" }, "examples": { "shared_space_to_account": { "summary": "Map a shared space path to a Box account folder", "value": { "job_id": "6a3ba68e810d9156194530a1", "source": { "type": "shared_space", "space": "HR Team Site", "path": "/Shared Documents", "path_id": "sp-folder-001", "is_directory": true }, "target": { "type": "account", "path": "/HR Migration", "path_id": "1234567890", "account": { "email": "admin@company.box.com" } } } }, "skip_path": { "summary": "Skip a source path", "value": { "job_id": "6a3ba68e810d9156194530a1", "is_path_skipped": true, "source": { "type": "shared_space", "space": "HR Team Site", "path": "/Archive", "is_directory": true }, "target": null } } } } } }, "responses": { "201": { "description": "Returns the newly created shuttle path mapping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttlePathMapping" } } } }, "400": { "description": "Returned when the request body is malformed or required fields are\nmissing.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the referenced shuttle job cannot be found or the user\ndoes not have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_path_mappings/{shuttle_path_mapping_id}": { "get": { "operationId": "get_shuttle_path_mappings_id_v2026.0", "summary": "Get shuttle path mapping by ID", "description": "Returns details for a single shuttle path mapping identified by its ID,\nincluding the source location and destination, if any.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_path_mapping_id", "in": "path", "description": "The unique identifier for the shuttle path mapping.", "required": true, "schema": { "type": "string" }, "example": "6a3ba7a24ea17bc9461eeacd" } ], "responses": { "200": { "description": "Returns the shuttle path mapping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttlePathMapping" } } } }, "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle path mapping is not found or the user does\nnot have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "put": { "operationId": "put_shuttle_path_mappings_id_v2026.0", "summary": "Update shuttle path mapping", "description": "Updates the mutable properties of an existing shuttle path mapping\nidentified by its ID. Only the fields supplied in the request body are\nchanged.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_path_mapping_id", "in": "path", "description": "The unique identifier for the shuttle path mapping.", "required": true, "schema": { "type": "string" }, "example": "6a3ba7a24ea17bc9461eeacd" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttlePathMappingUpdateRequest" }, "examples": { "skip_path": { "summary": "Skip a mapped path and clear the destination", "value": { "is_path_skipped": true, "target": null } } } } } }, "responses": { "200": { "description": "Returns the updated shuttle path mapping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttlePathMapping" } } } }, "400": { "description": "Returned when the request body is malformed, empty, or fails\nvalidation.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle path mapping is not found or the user does\nnot have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "delete": { "operationId": "delete_shuttle_path_mappings_id_v2026.0", "summary": "Delete shuttle path mapping", "description": "Permanently deletes the shuttle path mapping identified by its ID. This\ndoes not affect content that has already been migrated.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_path_mapping_id", "in": "path", "description": "The unique identifier for the shuttle path mapping.", "required": true, "schema": { "type": "string" }, "example": "6a3ba7a24ea17bc9461eeacd" } ], "responses": { "204": { "description": "Returns an empty response when the shuttle path mapping was\nsuccessfully deleted." }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the authenticated user is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle path mapping is not found or the user does\nnot have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_path_mapping_imports": { "post": { "operationId": "post_shuttle_path_mapping_imports_v2026.0", "summary": "Create shuttle path mapping import", "description": "Accepts a spreadsheet of path mappings, already stored in Box, and replaces\nthe job's path mappings.\nA file that is not a mapping workbook, or that exceeds the size or row\nlimits (10 MiB Box download limit; 100,000 mapping rows), returns `400`\nsynchronously and leaves the job unchanged.\nAn accepted import always replaces every path mapping on the job. When all\nrows are valid the workbook is deployed in full. When any row is invalid\nthe job ends with no path mappings and `mapping_state` becomes\n`paths_import_rejected` until the next import or the next manual\npath-mapping change. Row problems are listed by\n`GET /shuttle_mapping_errors?job_id=…` with category `path_import`, messages\nof the form `Row N: …`, at most 500 entries plus one overflow entry.\nValidation and deployment are asynchronous after acceptance. Poll\n`GET /shuttle_jobs/{shuttle_job_id}` while `mapping_state` is\n`importing_paths`. Only one import may be in flight per job.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttlePathMappingImportCreateRequest" }, "examples": { "workbook": { "summary": "Import path mappings from a Box file", "value": { "job_id": "6a3ba68e810d9156194530a1", "file_id": "12345678901" } } } } } }, "responses": { "202": { "description": "The import was accepted. Validation and deployment continue\nasynchronously. Poll `GET /shuttle_jobs/{shuttle_job_id}` until\n`mapping_state` is no longer `importing_paths`. A rejected import ends\nwith `mapping_state` `paths_import_rejected` and an empty path-mapping\nlist; a successful import moves on to a later mapping-preparation state\nsuch as `paths_ready` or `ready`." }, "400": { "description": "Returned when the request body is malformed or fails request validation,\nor when the referenced file cannot be accepted as a mapping workbook\n(for example it is not a spreadsheet, has no mapping sheets, or exceeds\nthe size or row limits). Nothing is stored and the job's path mappings\nare unchanged. Row-level mapping errors are not returned here; after a\n`202` they finish asynchronously as `paths_import_rejected` and appear\non `GET /shuttle_mapping_errors`.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found, or the referenced file does\nnot exist or cannot be read by the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returned when an import is already in progress for the shuttle job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_subject_mapping_imports": { "post": { "operationId": "post_shuttle_subject_mapping_imports_v2026.0", "summary": "Create shuttle subject mapping import", "description": "Accepts a spreadsheet of subject (user and group) mappings, already stored\nin Box, and replaces the job's subject mappings.\nA file that is not a subject-mapping workbook, or that exceeds the size or\nrow limits (10 MiB Box download limit; 50,000 mapping rows), returns `400`\nsynchronously and leaves the job unchanged.\nAn accepted import always replaces every subject mapping on the job. When\nall rows are valid the workbook is deployed in full. When any row is\ninvalid the job ends with no subject mappings and `mapping_state` becomes\n`subjects_import_rejected` until the next import or the next manual\nsubject-mapping change. Row problems are listed by\n`GET /shuttle_mapping_errors?job_id=…` with category `subject_import`,\nmessages of the form `Row N: …`, at most 500 entries plus one overflow\nentry.\nValidation and deployment are asynchronous after acceptance. Poll\n`GET /shuttle_jobs/{shuttle_job_id}` while `mapping_state` is\n`importing_subjects`. Only one import may be in flight per job. The job\nmust map subjects (`account_mapping` enabled) and its source scan must be\nfinished; otherwise the request returns `409`.\n\nExpected workbook format (API clients cannot download the UI template):\nsheets `Users` and/or `Groups` (a sheet named `Subjects` is also accepted).\nColumns are `Source User `, `Target User `, `Skip` on `Users`,\nand `Source Group `, `Target Group `, `Skip` on `Groups`, where\n`` is the primary identifier for that role and system:\n- Users: `Email` for most systems; `ID` for `SharePoint` (2007/2010/2013);\n `Name` for Windows (`windows_union`, stored as the user id).\n- Groups: `Name` for most systems; `Email` for Google Drive admin groups.\nSource rows for a template can be taken from\n`GET /shuttle_discovered_subjects`.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleSubjectMappingImportCreateRequest" }, "examples": { "workbook": { "summary": "Import subject mappings from a Box file", "value": { "job_id": "6a3ba68e810d9156194530a1", "file_id": "12345678901" } } } } } }, "responses": { "202": { "description": "The import was accepted. Validation and deployment continue\nasynchronously. Poll `GET /shuttle_jobs/{shuttle_job_id}` until\n`mapping_state` is no longer `importing_subjects`. A rejected import\nends with `mapping_state` `subjects_import_rejected` and an empty\nsubject-mapping list; a successful import moves on to a later\nmapping-preparation state such as `mapping_complete` or `ready`." }, "400": { "description": "Returned when the request body is malformed or fails request validation,\nor when the referenced file cannot be accepted as a subject-mapping\nworkbook (for example it is not a spreadsheet, has none of the `Users`,\n`Groups`, or `Subjects` sheets, or exceeds the size or row limits).\nNothing is stored and the job's subject mappings are unchanged.\nRow-level mapping errors are not returned here; after a `202` they\nfinish asynchronously as `subjects_import_rejected` and appear on\n`GET /shuttle_mapping_errors`.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found, or the referenced file does\nnot exist or cannot be read by the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returned when an import is already in progress for the shuttle job, the\njob does not map subjects, or the source scan has not finished (or is\nout of date relative to the current path mappings).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_subject_mappings": { "get": { "operationId": "get_shuttle_subject_mappings_v2026.0", "summary": "List shuttle subject mappings", "description": "Returns a paginated list of subject mappings for the shuttle job identified\nby `job_id`.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "job_id", "in": "query", "description": "The unique identifier of the shuttle job whose subject mappings to list.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of shuttle subject mappings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleSubjectMappings" } } } }, "400": { "description": "Returned when `job_id` is missing or the user has passed in a malformed\n`marker` or `limit` value.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "post": { "operationId": "post_shuttle_subject_mappings_v2026.0", "summary": "Create shuttle subject mapping", "description": "Creates a subject mapping that connects a discovered source subject to a\nBox user or group for the given shuttle job.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleSubjectMappingCreateRequest" }, "examples": { "map_user": { "summary": "Map a discovered user to a Box user", "value": { "job_id": "6a3ba68e810d9156194530a1", "discovered_subject_id": "6a3ba7c02ea17bc9461eeacf", "target": { "type": "user", "id": "12345678" } } }, "skip_subject": { "summary": "Skip a discovered subject", "value": { "job_id": "6a3ba68e810d9156194530a1", "discovered_subject_id": "6a3ba7c02ea17bc9461eeacf", "is_subject_skipped": true, "target": null } } } } } }, "responses": { "201": { "description": "Returns the newly created shuttle subject mapping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleSubjectMapping" } } } }, "400": { "description": "Returned when the request body is malformed or required fields are\nmissing.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the referenced shuttle job or discovered subject cannot\nbe found or the user does not have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returned when the provided revision does not match the current\ndiscovery-requirements revision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_subject_mappings/{shuttle_subject_mapping_id}": { "get": { "operationId": "get_shuttle_subject_mappings_id_v2026.0", "summary": "Get shuttle subject mapping by ID", "description": "Returns details for a single shuttle subject mapping identified by its ID,\nincluding the source subject and Box target, if any.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_subject_mapping_id", "in": "path", "description": "The unique identifier for the shuttle subject mapping.", "required": true, "schema": { "type": "string" }, "example": "6a3ba7b12ea17bc9461eeace" } ], "responses": { "200": { "description": "Returns the shuttle subject mapping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleSubjectMapping" } } } }, "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle subject mapping is not found or the user does\nnot have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "put": { "operationId": "put_shuttle_subject_mappings_id_v2026.0", "summary": "Update shuttle subject mapping", "description": "Updates the mutable properties of an existing shuttle subject mapping\nidentified by its ID. Only the fields supplied in the request body are\nchanged.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_subject_mapping_id", "in": "path", "description": "The unique identifier for the shuttle subject mapping.", "required": true, "schema": { "type": "string" }, "example": "6a3ba7b12ea17bc9461eeace" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleSubjectMappingUpdateRequest" }, "examples": { "skip_subject": { "summary": "Skip a mapped subject", "value": { "is_subject_skipped": true } }, "remap_subject": { "summary": "Map a subject to a Box user", "value": { "is_subject_skipped": false, "target": { "type": "user", "id": "12345678" } } } } } } }, "responses": { "200": { "description": "Returns the updated shuttle subject mapping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleSubjectMapping" } } } }, "400": { "description": "Returned when the request body is malformed, empty, or fails\nvalidation.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle subject mapping is not found or the user does\nnot have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "delete": { "operationId": "delete_shuttle_subject_mappings_id_v2026.0", "summary": "Delete shuttle subject mapping", "description": "Permanently deletes the shuttle subject mapping identified by its ID.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_subject_mapping_id", "in": "path", "description": "The unique identifier for the shuttle subject mapping.", "required": true, "schema": { "type": "string" }, "example": "6a3ba7b12ea17bc9461eeace" } ], "responses": { "204": { "description": "Returns an empty response when the shuttle subject mapping was\nsuccessfully deleted." }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the authenticated user is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle subject mapping is not found or the user does\nnot have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_discovered_subjects": { "get": { "operationId": "get_shuttle_discovered_subjects_v2026.0", "summary": "List shuttle discovered subjects", "description": "Returns a paginated list of subjects discovered on the source system for\nthe shuttle job identified by `job_id`.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "job_id", "in": "query", "description": "The unique identifier of the shuttle job whose discovered subjects to list.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of discovered subjects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleDiscoveredSubjects" } } } }, "400": { "description": "Returned when `job_id` is missing or the user has passed in a malformed\n`marker` or `limit` value.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_path_entries": { "get": { "operationId": "get_shuttle_path_entries_v2026.0", "summary": "List shuttle path entries", "description": "Returns a paginated list of source or target path entries for a shuttle\njob. Call with only `job_id` and `side` to list the roots, then browse one\nlevel at a time using `path`, `path_id`, or both. Each entry includes\n`path`, `path_id`, `is_directory`, and a `scope` object (`account` or\n`shared_space`) so a mapping can be created from that row without extra\nbrowse state. Valid values depend on the selected system.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "job_id", "in": "query", "description": "The unique identifier of the shuttle job whose path entries to list.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1" }, { "name": "side", "in": "query", "description": "The side of the migration to browse.", "required": true, "schema": { "type": "string", "enum": [ "source", "target" ] }, "example": "source" }, { "name": "path", "in": "query", "description": "The human-readable parent path whose children are returned. This can\nbe used with or without `path_id`. Omit both, or pass `/` as `path`,\nto list root entries.", "required": false, "schema": { "type": "string", "minLength": 1 }, "example": "/Shared Documents/Projects" }, { "name": "path_id", "in": "query", "description": "The `path_id` value of the parent entry whose children are\nreturned. This can be used with or without `path`. It distinguishes\npaths with identical names on systems that support stable identifiers.", "required": false, "schema": { "type": "string" }, "example": "01ABCDEF23456789" }, { "name": "account_email", "in": "query", "description": "The email of the account whose path entries are returned. This is a\nsystem-native identifier and is not always an RFC 5322 address.", "required": false, "schema": { "type": "string" }, "example": "user@example.com" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of shuttle path entries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttlePathEntries" } } } }, "400": { "description": "Returned when a required parameter is missing, a parameter is\nmalformed, or the selected system cannot browse the supplied\ncombination of `path` and `path_id`.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_mapping_errors": { "get": { "operationId": "get_shuttle_mapping_errors_v2026.0", "summary": "List shuttle mapping errors", "description": "Returns a paginated list of mapping errors for a shuttle job. Only the latest\nrecord for each error is returned. The revision field identifies the mapping\nrevision in which that error was generated.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "job_id", "in": "query", "description": "The unique identifier of the shuttle job whose mapping errors to list.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of shuttle mapping errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleMappingErrors" } } } }, "400": { "description": "Returned when `job_id` is missing or the user has passed in a malformed\n`marker` or `limit` value.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle job is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_reports": { "get": { "operationId": "get_shuttle_reports_v2026.0", "summary": "List shuttle reports", "description": "Returns a paginated list of reports generated for the shuttle run\nidentified by `run_id`.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "run_id", "in": "query", "description": "The unique identifier of the shuttle run whose reports to list.", "required": true, "schema": { "type": "string" }, "example": "6a3ba68e810d9156194530a1:42" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of shuttle reports.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleReports" } } } }, "400": { "description": "Returned when `run_id` is missing or the user has passed in a\nmalformed `marker` or `limit` value.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle run is not found or the user does not have\naccess to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] }, "post": { "operationId": "post_shuttle_reports_v2026.0", "summary": "Create shuttle report", "description": "Requests asynchronous generation of a report for a shuttle run. The\nreport is returned immediately in `pending` or `processing` status.\nPoll `GET /shuttle_reports/{shuttle_report_id}` while `status` is\n`pending` or `processing`. Stop when `status` is `complete`, `failed`,\n`canceled`, or `unknown`. Repeating this request with the same\nparameters reuses the existing report instead of creating a duplicate.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleReportCreateRequest" }, "examples": { "xlsx_event_log": { "summary": "Generate an Excel event log and transfer overview", "value": { "run_id": "6a3ba68e810d9156194530a1:42", "format": "xlsx", "sections": [ "event_log", "transfer_overview" ], "users_scope": "migrated" } } } } } }, "responses": { "202": { "description": "The report was accepted for generation. Returns the shuttle report;\ngeneration continues asynchronously. Repeating this request with the\nsame parameters reuses the existing report instead of creating a\nduplicate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleReport" } } } }, "400": { "description": "Returned when the request body is malformed, required fields are\nmissing, or `sections` is not a subset of the run's\n`available_report_sections`.", "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the referenced shuttle run cannot be found or the user\ndoes not have access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returned when a report cannot be generated for the run in its current\nstate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } }, "/shuttle_reports/{shuttle_report_id}": { "get": { "operationId": "get_shuttle_reports_id_v2026.0", "summary": "Get shuttle report by ID", "description": "Returns details for a single shuttle report identified by its ID,\nincluding generation status and, once generation finishes, the Box\noutput reference.", "parameters": [ { "$ref": "#/components/parameters/BoxVersionHeader" }, { "name": "shuttle_report_id", "in": "path", "description": "The unique identifier for the shuttle report.", "required": true, "schema": { "type": "string" }, "example": "6a3ba8d14f2c91e8370b4d12" } ], "responses": { "200": { "description": "Returns the shuttle report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShuttleReport" } } } }, "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 is not an admin or co-admin with\npermission to manage enterprise properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the shuttle report is not found or the user does not\nhave access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returned when the user has sent too many requests in a given amount of\ntime.", "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": "shuttle", "tags": [ "Shuttle" ] } } }, "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" }, "DocumentFailures": { "description": "Errors and warnings that occurred during a document job.", "type": "object", "properties": { "errors": { "description": "A list of errors that occurred during the document job.", "type": "array", "items": { "type": "string" }, "example": [ "The source file could not be processed." ] }, "warnings": { "description": "A list of warnings that occurred during the document job.", "type": "array", "items": { "type": "string" }, "example": [ "Some pages were skipped because they were blank." ] } }, "required": [ "errors", "warnings" ], "title": "Document failures" }, "DocumentSplit": { "description": "A standard representation of a Document Split job. The job represents a\nrequest to split a paginated source document into multiple files based on\neither a manual set of page ranges, a non-linear page selection, or a\nsmart prompt-driven analysis.", "type": "object", "properties": { "id": { "description": "The unique identifier for the Document Split job.", "type": "string", "example": "1748426" }, "type": { "description": "The value will always be `document_split`.", "type": "string", "example": "document_split", "enum": [ "document_split" ] }, "source_file": { "allOf": [ { "$ref": "#/components/schemas/FileReference" }, { "description": "The file to split." } ] }, "status": { "description": "The current state of the Document Split job.", "type": "string", "example": "submitted", "enum": [ "submitted", "completed", "failed", "completed_with_error" ] }, "split_input": { "allOf": [ { "$ref": "#/components/schemas/DocumentSplitCreateRequestType" }, { "description": "The caller-supplied input that was used to perform the split. The\nshape mirrors the request: for a `manual` split, `split_input`\ncontains `split_type` and `split_definition`; for a `page_selection`\nsplit, `split_input` contains `split_type` and `page_selection`; for\na `smart` split, `split_input` contains `split_type` and the\ncaller-supplied `prompt`. For smart splits, the page ranges that Box\nproduced are exposed under `output.split_definition`." } ] }, "output": { "description": "The result of the Document Split job. `null` until the job has produced\noutput.", "oneOf": [ { "$ref": "#/components/schemas/DocumentSplitOutput" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] }, "destination_folder": { "allOf": [ { "$ref": "#/components/schemas/FolderReference" }, { "description": "The folder that received the generated files." } ] }, "input_source": { "description": "The system that initiated the request, used for analytics and\ntraceability.", "type": "string", "example": "api", "enum": [ "api", "box", "relay", "salesforce" ] }, "created_at": { "description": "When the Document Split job was created.", "type": "string", "format": "date-time", "example": "2023-10-26T15:30:00Z" }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created the Document Split job." } ] }, "enterprise": { "allOf": [ { "$ref": "#/components/schemas/EnterpriseReference" }, { "description": "The enterprise that owns the Document Split job." } ] }, "failures": { "description": "Errors and warnings that occurred during the document split. `null` when\nno failures were recorded.", "oneOf": [ { "$ref": "#/components/schemas/DocumentSplitFailures" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] }, "external_id": { "description": "An optional identifier supplied by the caller when the Document Split\njob was created. Returned for correlation only. It is not a Box\nresource ID, is not required to be unique, and cannot be used to\nlook up the job.", "type": "string", "example": "invoice-48291", "maxLength": 255 } }, "required": [ "id", "type", "source_file", "destination_folder", "status", "split_input", "input_source" ], "title": "Document Split", "x-box-resource-id": "document_split_v2026.0", "x-box-tag": "document_split" }, "DocumentSplitCreateRequest": { "description": "The request body for creating a Document Split job. The `split_input`\nproperty carries the caller-supplied input that determines how the split\nis performed.", "type": "object", "properties": { "source_file_id": { "description": "The ID of the source file to split.", "type": "string", "example": "12345" }, "destination_folder_id": { "description": "The ID of the folder where the resulting files will be uploaded.", "type": "string", "example": "14047816008" }, "input_source": { "description": "The system that initiated the request, used for analytics and\ntraceability.", "type": "string", "example": "api", "enum": [ "api", "box", "relay", "salesforce" ] }, "split_input": { "$ref": "#/components/schemas/DocumentSplitCreateRequestType" }, "external_id": { "description": "An optional identifier supplied by the caller for this Document Split job.\nThe value is returned on job responses for correlation only. It is not\na Box resource ID, is not required to be unique, and cannot be used to\nlook up the job.", "type": "string", "example": "invoice-48291", "maxLength": 255 } }, "required": [ "source_file_id", "destination_folder_id", "input_source", "split_input" ], "title": "Document Split create request", "x-box-resource-id": "document_split_create_request_v2026.0", "x-box-tag": "document_split" }, "DocumentSplitCreateRequestManual": { "description": "Validation rules for creating a Document Split job using caller-supplied page\nranges.", "type": "object", "properties": { "split_type": { "description": "Discriminator. Must be `manual` for this variant.", "type": "string", "example": "manual", "enum": [ "manual" ] }, "version": { "description": "The version of the manual split input format. Omitted or `v_1` is the\nlegacy `split_definition` format. Existing clients may omit this field.", "type": "string", "example": "v_1", "enum": [ "v_1" ] }, "split_definition": { "description": "Page ranges that define the split. Each entry produces one output file\ncontaining the inclusive page range `[start, end]`.", "type": "array", "items": { "$ref": "#/components/schemas/DocumentSplitPageRange" }, "example": [ { "start": 1, "end": 5 }, { "start": 6, "end": 14 } ], "minItems": 1 } }, "not": { "anyOf": [ { "required": [ "prompt" ] }, { "required": [ "page_selection" ] } ] }, "required": [ "split_type", "split_definition" ], "title": "Document Split manual create request", "x-box-tag": "document_split" }, "DocumentSplitCreateRequestPageSelection": { "description": "Validation rules for creating a Document Split job using non-linear page\nselections. Each item produces one output file from the declared page\nsegments.", "type": "object", "properties": { "split_type": { "description": "Discriminator. Must be `page_selection` for this variant.", "type": "string", "example": "page_selection", "enum": [ "page_selection" ] }, "version": { "description": "The version of the page selection input format. Optional. When provided\nmust be `v_2`.", "type": "string", "example": "v_2", "enum": [ "v_2" ] }, "page_selection": { "$ref": "#/components/schemas/DocumentSplitPageSelection" } }, "not": { "anyOf": [ { "required": [ "prompt" ] }, { "required": [ "split_definition" ] } ] }, "required": [ "split_type", "page_selection" ], "title": "Document Split page selection create request", "x-box-tag": "document_split" }, "DocumentSplitCreateRequestSmart": { "description": "Validation rules for creating a Document Split job using Box-generated page\nranges guided by a caller-supplied prompt.", "type": "object", "properties": { "split_type": { "description": "Discriminator. Must be `smart` for this variant.", "type": "string", "example": "smart", "enum": [ "smart" ] }, "prompt": { "description": "A natural language prompt that guides automatic page range detection.", "type": "string", "example": "Split this contract into one file per signed section.", "minLength": 1 } }, "not": { "anyOf": [ { "required": [ "split_definition" ] }, { "required": [ "page_selection" ] } ] }, "required": [ "split_type", "prompt" ], "title": "Document Split smart create request", "x-box-tag": "document_split" }, "DocumentSplitCreateRequestType": { "description": "Validation rules for the supported Document Split create request types.", "oneOf": [ { "$ref": "#/components/schemas/DocumentSplitCreateRequestManual" }, { "$ref": "#/components/schemas/DocumentSplitCreateRequestPageSelection" }, { "$ref": "#/components/schemas/DocumentSplitCreateRequestSmart" } ], "title": "Document Split create request type", "x-box-tag": "document_split" }, "DocumentSplitCreateResponse": { "description": "A reference to a newly created Document Split job. Returned when a Document\nSplit job is accepted for asynchronous processing. Clients can poll the\nfull job representation using this ID.", "type": "object", "properties": { "type": { "description": "The value will always be `document_split`.", "type": "string", "example": "document_split", "enum": [ "document_split" ] }, "id": { "description": "The unique identifier of the created Document Split job.", "type": "string", "example": "1748426" } }, "required": [ "type", "id" ], "title": "Document Split create response", "x-box-resource-id": "document_split_create_response_v2026.0", "x-box-tag": "document_split" }, "DocumentSplitFailures": { "description": "Errors and warnings that occurred during a Document Split job.", "allOf": [ { "$ref": "#/components/schemas/DocumentFailures" } ], "title": "Document Split failures", "x-box-resource-id": "document_split_failures_v2026.0", "x-box-tag": "document_split" }, "DocumentSplitOutput": { "description": "The set of files produced by a completed Document Split job.", "type": "object", "properties": { "generated_files": { "description": "References to the files that were created by the split.", "type": "array", "items": { "$ref": "#/components/schemas/FileReference" } }, "split_definition": { "description": "The page ranges that Box produced for a `smart` split. Each entry\ncorresponds to one generated file with the inclusive page range\n`[start, end]`. Omitted or `null` for `manual` splits, where the\ncaller-supplied ranges are available in `split_input.split_definition`.\nOmitted for `page_selection` splits, where the caller-supplied page\nlayout is available in `split_input.page_selection`.", "type": "array", "items": { "$ref": "#/components/schemas/DocumentSplitPageRange" }, "example": [ { "start": 1, "end": 10 }, { "start": 11, "end": 25 } ], "nullable": true } }, "title": "Document Split output", "x-box-resource-id": "document_split_output_v2026.0", "x-box-tag": "document_split" }, "DocumentSplitPageRange": { "description": "An inclusive page range used to define one slice of a manual Document Split job.", "type": "object", "properties": { "start": { "description": "The first page (inclusive) included in this slice.", "type": "integer", "format": "int32", "example": 1, "minimum": 1 }, "end": { "description": "The last page (inclusive) included in this slice.", "type": "integer", "format": "int32", "example": 10, "minimum": 1 } }, "additionalProperties": false, "required": [ "start", "end" ], "title": "Document Split page range", "x-box-tag": "document_split" }, "DocumentSplitPageSelection": { "description": "Defines a non-sequential page selection for a Document Split job. Each item\nin the array produces one output PDF assembled from the declared page\nsegments.", "type": "array", "items": { "$ref": "#/components/schemas/DocumentSplitPageSelectionItem" }, "example": [ { "name": "exhibits", "segments": [ { "type": "single_page", "page": 4 }, { "type": "single_page", "page": 8 }, { "type": "page_range", "start": 6, "end": 8 } ] } ], "minItems": 1, "title": "Document Split page selection", "x-box-tag": "document_split" }, "DocumentSplitPageSelectionItem": { "description": "A single output file definition within a page selection request. Each item\nproduces one PDF containing the pages specified by its segments array.", "type": "object", "properties": { "name": { "description": "Optional name for the output file (without extension). When omitted the\nsystem generates a sequential name based on the source file name.", "type": "string", "example": "exhibits", "minLength": 1 }, "segments": { "description": "An ordered list of page segments to include in this output file. Each\nsegment specifies either a single page or a contiguous page range.", "type": "array", "items": { "$ref": "#/components/schemas/DocumentSplitPageSelectionSegment" }, "example": [ { "type": "single_page", "page": 4 }, { "type": "page_range", "start": 6, "end": 8 } ], "minItems": 1 } }, "required": [ "segments" ], "title": "Document Split page selection item", "x-box-tag": "document_split" }, "DocumentSplitPageSelectionPageRange": { "description": "A page selection segment that includes an inclusive page range from the\nsource document.", "type": "object", "properties": { "type": { "description": "Discriminator. Must be `page_range` for this variant.", "type": "string", "example": "page_range", "enum": [ "page_range" ] }, "start": { "description": "The first page (inclusive) included in this segment.", "type": "integer", "format": "int32", "example": 6, "minimum": 1 }, "end": { "description": "The last page (inclusive) included in this segment.", "type": "integer", "format": "int32", "example": 8, "minimum": 1 } }, "additionalProperties": false, "required": [ "type", "start", "end" ], "title": "Document Split page selection page range", "x-box-tag": "document_split" }, "DocumentSplitPageSelectionSegment": { "description": "A single page segment within a page selection item. The `type` field\nidentifies whether the segment is a single page or an inclusive page range.", "oneOf": [ { "$ref": "#/components/schemas/DocumentSplitPageSelectionSinglePage" }, { "$ref": "#/components/schemas/DocumentSplitPageSelectionPageRange" } ], "title": "Document Split page selection segment", "x-box-tag": "document_split" }, "DocumentSplitPageSelectionSinglePage": { "description": "A page selection segment that includes a single page from the source\ndocument.", "type": "object", "properties": { "type": { "description": "Discriminator. Must be `single_page` for this variant.", "type": "string", "example": "single_page", "enum": [ "single_page" ] }, "page": { "description": "A single page number to include.", "type": "integer", "format": "int32", "example": 4, "minimum": 1 } }, "additionalProperties": false, "required": [ "type", "page" ], "title": "Document Split page selection single page", "x-box-tag": "document_split" }, "DocumentSplits": { "description": "A paginated list of Document Split jobs.", "type": "object", "allOf": [ { "properties": { "entries": { "description": "A list of Document Split jobs.", "type": "array", "items": { "$ref": "#/components/schemas/DocumentSplit" } } } }, { "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": "Document Splits", "x-box-resource-id": "document_splits_v2026.0", "x-box-tag": "document_split" }, "EnterpriseReference": { "description": "A reference to an enterprise, used when\nnested within another resource.", "type": "object", "properties": { "id": { "description": "The unique identifier for this enterprise.", "type": "string", "example": "1910967" }, "type": { "description": "The value will always be `enterprise`.", "type": "string", "example": "enterprise", "enum": [ "enterprise" ], "nullable": false } }, "required": [ "type", "id" ], "title": "Enterprise reference" }, "FileReference": { "description": "File reference.", "type": "object", "properties": { "type": { "description": "The value will always be `file`.", "type": "string", "example": "file", "enum": [ "file" ], "nullable": false }, "id": { "description": "ID of the file.", "type": "string", "example": "42037322", "nullable": false } }, "required": [ "type", "id" ], "title": "File reference" }, "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" }, "ShuttleAgentCredentials": { "description": "The installation credentials issued for a Windows shuttle system. The\nregistration token is pasted into the Windows agent installer to register\nthe agent with its system.", "type": "object", "properties": { "registration_token": { "description": "The installation token to paste into the Windows agent installer to\nregister the agent.", "type": "string", "example": "eyJhbGciOi..." }, "expires_at": { "description": "When the registration token expires and can no longer be used.", "type": "string", "format": "date-time", "example": "2026-03-16T12:00:00Z" } }, "required": [ "registration_token", "expires_at" ], "title": "Shuttle agent credentials", "x-box-resource-id": "shuttle_agent_credentials_v2026.0", "x-box-tag": "shuttle" }, "ShuttleDiscoveredSubject": { "description": "A subject discovered on the source system during a scan, with an optional\nsuggested Box target.", "type": "object", "properties": { "id": { "description": "The unique identifier for the discovered subject.", "type": "string", "example": "6a315c0754833bfc5df067bf" }, "type": { "description": "The value will always be `shuttle_discovered_subject`.", "type": "string", "example": "shuttle_discovered_subject", "enum": [ "shuttle_discovered_subject" ] }, "job_id": { "description": "The unique identifier of the shuttle job this subject belongs to.", "type": "string", "example": "6a3ba68e810d9156194530a1" }, "revision": { "description": "The scan revision this discovered subject belongs to.", "type": "integer", "format": "int32", "example": 3 }, "source": { "allOf": [ { "$ref": "#/components/schemas/ShuttleSubject" }, { "description": "The source subject as discovered." } ] }, "suggested_target": { "description": "A suggested Box target inferred during the scan. `null` when no\nsuggestion was made.", "example": { "type": "user", "id": "12345678", "email": "user@example.com", "name": "Jane Doe" }, "oneOf": [ { "$ref": "#/components/schemas/ShuttleTargetSubject" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] } }, "required": [ "id", "type", "job_id", "revision", "source" ], "title": "Shuttle discovered subject", "x-box-resource-id": "shuttle_discovered_subject_v2026.0", "x-box-tag": "shuttle" }, "ShuttleDiscoveredSubjects": { "description": "A paginated list of subjects discovered on the source system.", "type": "object", "allOf": [ { "required": [ "entries" ], "properties": { "entries": { "description": "A list of discovered subjects.", "type": "array", "items": { "$ref": "#/components/schemas/ShuttleDiscoveredSubject" } } } }, { "type": "object", "description": "The part of an API response that describes marker\nbased pagination.", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } } ], "title": "Shuttle discovered subjects", "x-box-resource-id": "shuttle_discovered_subjects_v2026.0", "x-box-tag": "shuttle" }, "ShuttleJob": { "description": "A standard representation of a shuttle job. A shuttle job describes a\nmigration of content from a source system into Box, including its current\nstate, mapping-preparation state, and mapping configuration.", "type": "object", "properties": { "id": { "description": "The unique identifier for the shuttle job.", "type": "string", "example": "6a3ba68e810d9156194530a1" }, "type": { "description": "The value will always be `shuttle_job`.", "type": "string", "example": "shuttle_job", "enum": [ "shuttle_job" ] }, "name": { "description": "The human-readable name of the shuttle job.", "type": "string", "example": "Q4 SharePoint to Box" }, "comment": { "description": "An optional free-form comment describing the shuttle job.", "type": "string", "example": "Migrating the finance department archives.", "nullable": true }, "job_type": { "description": "The type of work the shuttle job performs.", "type": "string", "example": "transfer", "enum": [ "transfer", "analysis" ] }, "state": { "description": "The current state of the shuttle job. This is an open string whose set\nof values is expected to grow; the currently documented values include\n`created`, `started`, `stopped`, `completed`, `failed`, `invalid`, and\n`unknown`. Clients should treat any value they do not recognize as\n`unknown`.", "type": "string", "example": "created" }, "mapping_state": { "description": "The current mapping-preparation state of the job. This is an open string\nwhose set of values is expected to grow; the currently documented values\ninclude `awaiting_path_mapping`, `importing_paths`,\n`paths_import_rejected`, `paths_invalid`, `paths_ready`,\n`scanning_source`, `source_scan_failed`, `source_scan_out_of_date`,\n`awaiting_subject_mapping`, `importing_subjects`,\n`subjects_import_rejected`, `mapping_complete`, `building_map`,\n`map_build_failed`, `map_out_of_date`, and `ready`.\n`paths_import_rejected` means the last path-mapping spreadsheet was\nrejected or failed and the path mappings have not been changed since;\nit clears on the next import or the next manual path-mapping change.\n`subjects_import_rejected` means the last subject-mapping spreadsheet\nwas rejected or failed and the subject mappings have not been changed\nsince; it clears on the next import or the next manual subject-mapping\nchange.", "type": "string", "example": "awaiting_path_mapping" }, "source_system": { "description": "The source system the shuttle job migrates content from.", "type": "object", "properties": { "type": { "description": "The value will always be `shuttle_system`.", "type": "string", "example": "shuttle_system", "enum": [ "shuttle_system" ] }, "id": { "description": "The unique identifier for the source system.", "type": "string", "example": "6a3ba68e810d9156194530a1" }, "name": { "description": "The human-readable name of the source system.", "type": "string", "example": "SharePoint" } }, "required": [ "type", "id", "name" ], "x-box-tag": "shuttle" }, "account_mapping": { "description": "The account mapping configuration that controls how source identities\nand permissions are translated into Box.", "type": "object", "properties": { "is_enabled": { "description": "Whether account mapping is enabled for the shuttle job.", "type": "boolean", "example": true }, "permission_conflict_strategy": { "description": "The strategy used to resolve permission conflicts. `null` when\nunset.", "example": "preserve_structure_restrict_sharing", "oneOf": [ { "$ref": "#/components/schemas/ShuttleJobPermissionConflictStrategy" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] }, "are_external_shares_mapped": { "description": "Whether external shares are mapped during the migration.", "type": "boolean", "example": false }, "are_permissions_mapped": { "description": "Whether permissions are mapped during the migration.", "type": "boolean", "example": true } }, "required": [ "is_enabled" ], "x-box-tag": "shuttle" }, "tags": { "description": "A list of free-form tags associated with the shuttle job.", "type": "array", "items": { "type": "string", "description": "A single tag associated with the shuttle job.", "example": "q4" }, "example": [ "q4", "hr" ] }, "settings": { "description": "The tunable settings that control how the shuttle job runs.", "type": "object", "properties": { "bandwidth_limit_bytes_per_sec": { "description": "The maximum transfer bandwidth in bytes per second. `null` when\nunlimited.", "type": "integer", "format": "int64", "example": 10485760, "nullable": true }, "are_deletions_mirrored": { "description": "Whether deletions in the source system are mirrored in Box.", "type": "boolean", "example": false }, "are_file_versions_synced": { "description": "Whether prior file versions are synced during the migration.", "type": "boolean", "example": true }, "max_file_versions": { "description": "The maximum number of file versions to sync. `null` when unlimited.", "type": "integer", "format": "int32", "example": 10, "nullable": true }, "is_overwrite_enabled": { "description": "Whether existing files in Box are overwritten.", "type": "boolean", "example": false }, "are_completed_mappings_skipped_on_rerun": { "description": "Whether mappings that already completed successfully are skipped when\nthe job is rerun.", "type": "boolean", "example": true }, "is_content_scanning_enabled": { "description": "Whether migrated content is scanned during the migration. Applies\nonly when the source system supports content scanning; ignored\notherwise.", "type": "boolean", "example": false }, "include_shared_source_folders": { "description": "Whether shared folders on the source are included in the migration.\nApplies only when the source system supports shared folders; ignored\notherwise.", "type": "boolean", "example": true }, "include_shared_destination_folders": { "description": "Whether shared folders on the destination are included in the\nmigration. Applies only when the destination system supports shared\nfolders; ignored otherwise.", "type": "boolean", "example": false } }, "x-box-tag": "shuttle" } }, "required": [ "id", "type", "name", "job_type", "state", "mapping_state", "source_system" ], "title": "Shuttle job", "x-box-resource-id": "shuttle_job_v2026.0", "x-box-tag": "shuttle" }, "ShuttleJobCreateRequest": { "description": "The request body used to create a new shuttle job.", "type": "object", "properties": { "name": { "description": "The human-readable name of the shuttle job.", "type": "string", "example": "Q4 SharePoint to Box", "minLength": 1 }, "job_type": { "description": "The type of work the shuttle job performs.", "type": "string", "example": "transfer", "enum": [ "transfer", "analysis" ] }, "source_system_id": { "description": "The unique identifier of the source system to migrate from.", "type": "string", "example": "6a3ba68e810d9156194530a1" }, "comment": { "description": "An optional free-form comment describing the shuttle job.", "type": "string", "example": "Migrating the finance department archives." }, "tags": { "description": "A list of free-form tags associated with the shuttle job.", "type": "array", "items": { "type": "string", "description": "A single tag associated with the shuttle job.", "example": "q4" }, "example": [ "q4", "hr" ] }, "account_mapping": { "description": "The account mapping configuration that controls how source identities\nand permissions are translated into Box. When this object is omitted,\nthe job is created with `is_enabled` set to `false`.", "type": "object", "properties": { "is_enabled": { "description": "Whether account mapping is enabled for the shuttle job. Defaults to\n`false` when `account_mapping` is omitted on create.", "type": "boolean", "example": true }, "permission_conflict_strategy": { "description": "The strategy used to resolve permission conflicts. `null` when\nunset.", "example": "preserve_structure_restrict_sharing", "oneOf": [ { "$ref": "#/components/schemas/ShuttleJobPermissionConflictStrategy" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] }, "are_external_shares_mapped": { "description": "Whether external shares are mapped during the migration.", "type": "boolean", "example": false }, "are_permissions_mapped": { "description": "Whether permissions are mapped during the migration.", "type": "boolean", "example": true } }, "x-box-tag": "shuttle" }, "settings": { "description": "The tunable settings that control how the shuttle job runs.", "type": "object", "properties": { "bandwidth_limit_bytes_per_sec": { "description": "The maximum transfer bandwidth in bytes per second. `null` when\nunlimited.", "type": "integer", "format": "int64", "example": 10485760, "nullable": true }, "are_deletions_mirrored": { "description": "Whether deletions in the source system are mirrored in Box.", "type": "boolean", "example": false }, "are_file_versions_synced": { "description": "Whether prior file versions are synced during the migration.", "type": "boolean", "example": true }, "max_file_versions": { "description": "The maximum number of file versions to sync. `null` when unlimited.", "type": "integer", "format": "int32", "example": 10, "nullable": true }, "is_overwrite_enabled": { "description": "Whether existing files in Box are overwritten.", "type": "boolean", "example": false }, "are_completed_mappings_skipped_on_rerun": { "description": "Whether mappings that already completed successfully are skipped when\nthe job is rerun.", "type": "boolean", "example": true }, "is_content_scanning_enabled": { "description": "Whether migrated content is scanned during the migration. Applies\nonly when the source system supports content scanning; ignored\notherwise.", "type": "boolean", "example": false }, "include_shared_source_folders": { "description": "Whether shared folders on the source are included in the migration.\nApplies only when the source system supports shared folders; ignored\notherwise.", "type": "boolean", "example": true }, "include_shared_destination_folders": { "description": "Whether shared folders on the destination are included in the\nmigration. Applies only when the destination system supports shared\nfolders; ignored otherwise.", "type": "boolean", "example": false } }, "x-box-tag": "shuttle" } }, "required": [ "name", "job_type", "source_system_id" ], "title": "Shuttle job create request", "x-box-resource-id": "shuttle_job_create_request_v2026.0", "x-box-tag": "shuttle" }, "ShuttleJobPermissionConflictStrategy": { "description": "The strategy used to resolve permission conflicts.", "type": "string", "example": "preserve_structure_restrict_sharing", "enum": [ "preserve_structure_restrict_sharing", "preserve_structure_expand_sharing", "preserve_sharing_modify_structure", "warn_permissions_conflicts" ], "title": "Shuttle job permission conflict strategy", "x-box-resource-id": "shuttle_job_permission_conflict_strategy_v2026.0", "x-box-tag": "shuttle" }, "ShuttleJobs": { "description": "A paginated list of shuttle jobs.", "type": "object", "allOf": [ { "required": [ "entries" ], "properties": { "entries": { "description": "A list of shuttle jobs.", "type": "array", "items": { "$ref": "#/components/schemas/ShuttleJob" } } } }, { "type": "object", "description": "The part of an API response that describes marker\nbased pagination.", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } } ], "title": "Shuttle jobs", "x-box-resource-id": "shuttle_jobs_v2026.0", "x-box-tag": "shuttle" }, "ShuttleJobSchedule": { "description": "A schedule that starts runs of a shuttle job. A schedule is either\ntime-based or triggered by another job's run. Schedules cannot start a\nrun in `scan` mode.", "type": "object", "properties": { "id": { "description": "The unique identifier for the shuttle job schedule.", "type": "string", "example": "7c1ba68e810d9156194530b2" }, "type": { "description": "The value will always be `shuttle_job_schedule`.", "type": "string", "example": "shuttle_job_schedule", "enum": [ "shuttle_job_schedule" ] }, "job_id": { "description": "The unique identifier of the shuttle job this schedule belongs to.", "type": "string", "example": "6a3ba68e810d9156194530a1" }, "state": { "description": "Whether the schedule is active.", "type": "string", "example": "enabled", "enum": [ "enabled", "paused" ] }, "run_mode": { "description": "The kind of run the schedule starts. `scan` is not a valid schedule\nrun mode.", "type": "string", "example": "transfer", "enum": [ "transfer", "simulation", "analysis" ] }, "description": { "description": "An optional human-readable description of the schedule.", "type": "string", "example": "Nightly finance share replay.", "nullable": true }, "last_attempt_at": { "description": "When the schedule last attempted to start a run. `null` when the\nschedule has never started a run.", "type": "string", "format": "date-time", "example": "2026-03-16T09:00:12Z", "nullable": true }, "trigger": { "$ref": "#/components/schemas/ShuttleJobScheduleTrigger" } }, "required": [ "id", "type", "job_id", "state", "run_mode", "trigger" ], "title": "Shuttle job schedule", "x-box-resource-id": "shuttle_job_schedule_v2026.0", "x-box-tag": "shuttle" }, "ShuttleJobScheduleCreateRequest": { "description": "The request body used to create a shuttle job schedule.", "type": "object", "properties": { "job_id": { "description": "The unique identifier of the shuttle job this schedule belongs to.", "type": "string", "example": "6a3ba68e810d9156194530a1" }, "run_mode": { "description": "The kind of run the schedule starts. `scan` is not a valid schedule\nrun mode.", "type": "string", "example": "transfer", "enum": [ "transfer", "simulation", "analysis" ] }, "state": { "description": "Whether the schedule is active. When omitted, defaults to `enabled`.", "type": "string", "example": "enabled", "default": "enabled", "enum": [ "enabled", "paused" ] }, "description": { "description": "An optional human-readable description of the schedule.", "type": "string", "example": "Nightly finance share replay.", "nullable": true }, "trigger": { "$ref": "#/components/schemas/ShuttleJobScheduleTrigger" } }, "required": [ "job_id", "run_mode", "trigger" ], "title": "Shuttle job schedule create request", "x-box-resource-id": "shuttle_job_schedule_create_request_v2026.0", "x-box-tag": "shuttle" }, "ShuttleJobSchedules": { "description": "A paginated list of shuttle job schedules.", "type": "object", "allOf": [ { "required": [ "entries" ], "properties": { "entries": { "description": "A list of shuttle job schedules.", "type": "array", "items": { "$ref": "#/components/schemas/ShuttleJobSchedule" } } } }, { "type": "object", "description": "The part of an API response that describes marker\nbased pagination.", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } } ], "title": "Shuttle job schedules", "x-box-resource-id": "shuttle_job_schedules_v2026.0", "x-box-tag": "shuttle" }, "ShuttleJobScheduleTrigger": { "description": "When a shuttle job schedule should start a run. Exactly one trigger\nvariant is present, discriminated by `type`.", "oneOf": [ { "$ref": "#/components/schemas/ShuttleJobScheduleTriggerByTime" }, { "$ref": "#/components/schemas/ShuttleJobScheduleTriggerByJob" } ], "title": "Shuttle job schedule trigger", "x-box-resource-id": "shuttle_job_schedule_trigger_v2026.0", "x-box-tag": "shuttle" }, "ShuttleJobScheduleTriggerByJob": { "description": "A job-based trigger that starts this schedule after another shuttle\njob's run meets a condition.", "type": "object", "properties": { "type": { "description": "The value will always be `by_job`.", "type": "string", "example": "by_job", "enum": [ "by_job" ] }, "triggered_by_job_id": { "description": "The unique identifier of the shuttle job whose run starts this\nschedule.", "type": "string", "example": "8d2ca68e810d9156194530c3" }, "last_run_condition": { "description": "When this schedule should start a run relative to the last run of\nthe triggering job.", "type": "string", "example": "on_success", "enum": [ "always", "on_success", "on_finish" ] } }, "required": [ "type", "triggered_by_job_id", "last_run_condition" ], "title": "Shuttle job schedule trigger by job", "x-box-resource-id": "shuttle_job_schedule_trigger_by_job_v2026.0", "x-box-tag": "shuttle" }, "ShuttleJobScheduleTriggerByTime": { "description": "A time-based trigger that starts the schedule at a wall-clock time and\noptionally repeats.", "type": "object", "properties": { "type": { "description": "The value will always be `by_time`.", "type": "string", "example": "by_time", "enum": [ "by_time" ] }, "start_at": { "description": "The local wall-clock time when the schedule should first start a\nrun, without an offset or `Z` suffix. Combined with `time_zone` to\ndetermine the instant, including DST.", "type": "string", "example": "2026-03-16T09:00:00", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$" }, "time_zone": { "description": "The IANA time zone that gives `start_at` its calendar meaning (for\nexample `America/Los_Angeles`). Recurrence and DST transitions are\nevaluated in this zone.", "type": "string", "example": "America/Los_Angeles" }, "repeat": { "description": "How often the schedule repeats after `start_at`.", "type": "string", "example": "daily", "enum": [ "none", "daily", "weekly", "weekdays", "weekends" ] } }, "required": [ "type", "start_at", "time_zone", "repeat" ], "title": "Shuttle job schedule trigger by time", "x-box-resource-id": "shuttle_job_schedule_trigger_by_time_v2026.0", "x-box-tag": "shuttle" }, "ShuttleJobScheduleUpdateRequest": { "description": "The request body used to update an existing shuttle job schedule. Only\nthe fields supplied in the request body are changed.", "type": "object", "properties": { "state": { "description": "Whether the schedule is active.", "type": "string", "example": "paused", "enum": [ "enabled", "paused" ] }, "run_mode": { "description": "The kind of run the schedule starts. `scan` is not a valid schedule\nrun mode.", "type": "string", "example": "simulation", "enum": [ "transfer", "simulation", "analysis" ] }, "description": { "description": "An optional human-readable description of the schedule.", "type": "string", "example": "Nightly finance share replay.", "nullable": true }, "trigger": { "$ref": "#/components/schemas/ShuttleJobScheduleTrigger" } }, "minProperties": 1, "title": "Shuttle job schedule update request", "x-box-resource-id": "shuttle_job_schedule_update_request_v2026.0", "x-box-tag": "shuttle" }, "ShuttleJobStartRequest": { "description": "The request body used to start a shuttle job.", "type": "object", "properties": { "mode": { "description": "The run mode. Defaults to simulation when omitted.", "type": "string", "example": "simulation", "enum": [ "transfer", "simulation", "scan", "analysis" ] } }, "title": "Shuttle job start request", "x-box-resource-id": "shuttle_job_start_request_v2026.0", "x-box-tag": "shuttle" }, "ShuttleJobUpdateRequest": { "description": "The request body used to update an existing shuttle job. Only the fields\nsupplied in the request body are changed.", "type": "object", "properties": { "name": { "description": "The human-readable name of the shuttle job.", "type": "string", "example": "Q4 SharePoint to Box", "minLength": 1 }, "comment": { "description": "An optional free-form comment describing the shuttle job.", "type": "string", "example": "Migrating the finance department archives.", "nullable": true }, "tags": { "description": "A list of free-form tags associated with the shuttle job.", "type": "array", "items": { "type": "string", "description": "A single tag associated with the shuttle job.", "example": "q4" }, "example": [ "q4", "hr" ] }, "account_mapping": { "description": "The account mapping configuration that controls how source identities\nand permissions are translated into Box.", "type": "object", "properties": { "is_enabled": { "description": "Whether account mapping is enabled for the shuttle job.", "type": "boolean", "example": true }, "permission_conflict_strategy": { "description": "The strategy used to resolve permission conflicts. `null` when\nunset.", "example": "preserve_structure_restrict_sharing", "oneOf": [ { "$ref": "#/components/schemas/ShuttleJobPermissionConflictStrategy" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] }, "are_external_shares_mapped": { "description": "Whether external shares are mapped during the migration.", "type": "boolean", "example": false }, "are_permissions_mapped": { "description": "Whether permissions are mapped during the migration.", "type": "boolean", "example": true } }, "x-box-tag": "shuttle" }, "settings": { "description": "The tunable settings that control how the shuttle job runs.", "type": "object", "properties": { "bandwidth_limit_bytes_per_sec": { "description": "The maximum transfer bandwidth in bytes per second. `null` when\nunlimited.", "type": "integer", "format": "int64", "example": 10485760, "nullable": true }, "are_deletions_mirrored": { "description": "Whether deletions in the source system are mirrored in Box.", "type": "boolean", "example": false }, "are_file_versions_synced": { "description": "Whether prior file versions are synced during the migration.", "type": "boolean", "example": true }, "max_file_versions": { "description": "The maximum number of file versions to sync. `null` when unlimited.", "type": "integer", "format": "int32", "example": 10, "nullable": true }, "is_overwrite_enabled": { "description": "Whether existing files in Box are overwritten.", "type": "boolean", "example": false }, "are_completed_mappings_skipped_on_rerun": { "description": "Whether mappings that already completed successfully are skipped when\nthe job is rerun.", "type": "boolean", "example": true }, "is_content_scanning_enabled": { "description": "Whether migrated content is scanned during the migration. Applies\nonly when the source system supports content scanning; ignored\notherwise.", "type": "boolean", "example": false }, "include_shared_source_folders": { "description": "Whether shared folders on the source are included in the migration.\nApplies only when the source system supports shared folders; ignored\notherwise.", "type": "boolean", "example": true }, "include_shared_destination_folders": { "description": "Whether shared folders on the destination are included in the\nmigration. Applies only when the destination system supports shared\nfolders; ignored otherwise.", "type": "boolean", "example": false } }, "x-box-tag": "shuttle" } }, "minProperties": 1, "title": "Shuttle job update request", "x-box-resource-id": "shuttle_job_update_request_v2026.0", "x-box-tag": "shuttle" }, "ShuttleMappingError": { "description": "A problem encountered while preparing path, subject, or permission\nmappings for a shuttle job.", "type": "object", "properties": { "id": { "description": "The unique identifier for the mapping error.", "type": "string", "example": "6a3ba7c02ea17bc9461eeacf" }, "type": { "description": "The value will always be `shuttle_mapping_error`.", "type": "string", "example": "shuttle_mapping_error", "enum": [ "shuttle_mapping_error" ] }, "job_id": { "description": "The unique identifier of the shuttle job this error belongs to.", "type": "string", "example": "6a3ba68e810d9156194530a1" }, "revision": { "description": "The mapping revision this error belongs to.", "type": "integer", "format": "int32", "example": 3, "minimum": 0 }, "category": { "description": "The category of mapping work that produced the error. This is an open\nstring whose set of values can grow.", "type": "string", "example": "path" }, "path": { "description": "The path or subject that the mapping error refers to.", "type": "string", "example": "/Shared Documents/Projects" }, "messages": { "description": "Human-readable messages describing the mapping error.", "type": "array", "items": { "type": "string", "example": "The source path could not be resolved." }, "example": [ "The source path could not be resolved." ], "minItems": 1 } }, "required": [ "id", "type", "job_id", "revision", "category", "path", "messages" ], "title": "Shuttle mapping error", "x-box-resource-id": "shuttle_mapping_error_v2026.0", "x-box-tag": "shuttle" }, "ShuttleMappingErrors": { "description": "A paginated list of shuttle mapping errors.", "type": "object", "allOf": [ { "required": [ "entries" ], "properties": { "entries": { "description": "A list of shuttle mapping errors.", "type": "array", "items": { "$ref": "#/components/schemas/ShuttleMappingError" } } } }, { "type": "object", "description": "The part of an API response that describes marker\nbased pagination.", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } } ], "title": "Shuttle mapping errors", "x-box-resource-id": "shuttle_mapping_errors_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathEntries": { "description": "A paginated list of shuttle path entries.", "type": "object", "allOf": [ { "required": [ "entries" ], "properties": { "entries": { "description": "A list of shuttle path entries.", "type": "array", "items": { "$ref": "#/components/schemas/ShuttlePathEntry" } } } }, { "type": "object", "description": "The part of an API response that describes marker\nbased pagination.", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } } ], "title": "Shuttle path entries", "x-box-resource-id": "shuttle_path_entries_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathEntry": { "description": "A browsable entry on the source or target system used to build shuttle\npath mappings. Shared fields describe the node. `scope` is a\ndiscriminated object that identifies the mapping namespace so a path\nmapping can be created from this row without extra browse state.", "type": "object", "properties": { "id": { "description": "The unique identifier of this browse row. This is not the account\nidentifier; when `scope.type` is `account`, the account identifier is\n`scope.id`.", "type": "string", "example": "6a3ba7c02ea17bc9461eeacf" }, "type": { "description": "The value will always be `shuttle_path_entry`.", "type": "string", "example": "shuttle_path_entry", "enum": [ "shuttle_path_entry" ] }, "name": { "description": "The display name of the path entry.", "type": "string", "example": "Projects" }, "path": { "description": "The human-readable path of the entry.", "type": "string", "example": "/Shared Documents/Projects" }, "path_id": { "description": "The system-native identifier of the path. `null` when the selected\nsystem does not provide one. Maps to `path_id` on a path mapping\nlocation.", "type": "string", "example": "01ABCDEF23456789", "nullable": true }, "parent_path": { "description": "The human-readable path of the parent entry, or `null` for a root\nentry.", "type": "string", "example": "/Shared Documents", "nullable": true }, "scope": { "example": { "type": "shared_space", "space": "HR Team Site" }, "allOf": [ { "$ref": "#/components/schemas/ShuttlePathEntryScope" }, { "description": "The mapping namespace of this entry. Exactly one variant is\npresent, discriminated by `type`. An `account` scope is the\nowning account flattened onto the object. A `shared_space`\nscope carries the container name. Whether the entry is a file\nor a folder is indicated by `is_directory`, not by `scope`." } ] }, "is_directory": { "description": "Whether the entry is a directory (`true`) or a single file\n(`false`). Maps to `is_directory` on a path mapping location.", "type": "boolean", "example": true }, "can_map": { "description": "Whether the entry can be selected in a path mapping.", "type": "boolean", "example": true } }, "required": [ "id", "type", "name", "path", "scope", "is_directory", "can_map" ], "title": "Shuttle path entry", "x-box-resource-id": "shuttle_path_entry_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathEntryAccountScope": { "description": "The mapping scope of a path entry that lives under a user or service\naccount. `type` is the discriminator. The remaining fields are the\naccount itself, flattened onto this object — they are not a nested\n`account` wrapper. `id` here is the account identifier, not the path\nentry `id`. Copy these fields onto `account` when creating an\naccount-scoped path mapping.", "type": "object", "properties": { "type": { "description": "The value will always be `account`.", "type": "string", "example": "account", "enum": [ "account" ] }, "id": { "description": "The platform-native identifier of the account that owns this entry.\n`null` when the system does not provide one. This is not the path\nentry `id`. Maps to `account.id` on an account-scoped path mapping\nlocation.", "type": "string", "example": "123456", "nullable": true }, "email": { "description": "The email of the account that owns this entry. This is a\nsystem-native identifier and is not always an RFC 5322 address.\n`null` when unknown. Maps to `account.email` on an account-scoped\npath mapping location.", "type": "string", "example": "user@example.com", "nullable": true }, "name": { "description": "The display name of the account that owns this entry. `null` when\nunknown. Maps to `account.name` on an account-scoped path mapping\nlocation.", "type": "string", "example": "Jane Doe", "nullable": true } }, "required": [ "type" ], "title": "Shuttle path entry account scope", "x-box-resource-id": "shuttle_path_entry_account_scope_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathEntryScope": { "description": "Which mapping namespace this path entry belongs to. Discriminated by\n`type`: `account` flattens the owning account onto the object;\n`shared_space` carries the shared container name. File versus folder\nis not part of scope. Use `is_directory` on the path entry.", "oneOf": [ { "$ref": "#/components/schemas/ShuttlePathEntryAccountScope" }, { "$ref": "#/components/schemas/ShuttlePathEntrySharedSpaceScope" } ], "title": "Shuttle path entry scope", "x-box-resource-id": "shuttle_path_entry_scope_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathEntrySharedSpaceScope": { "description": "The mapping scope of a path entry that lives under a shared container\nsuch as a site, team drive, bucket, or file share. `type` is the\ndiscriminator. Copy `space` onto a shared-space path mapping location\nwhen creating a mapping from this row.", "type": "object", "properties": { "type": { "description": "The value will always be `shared_space`.", "type": "string", "example": "shared_space", "enum": [ "shared_space" ] }, "space": { "description": "The display name of the shared container this entry belongs to.\n`null` when the system has a single implicit container. Maps to\n`space` on a shared-space path mapping location.", "type": "string", "example": "HR Team Site", "nullable": true } }, "required": [ "type" ], "title": "Shuttle path entry shared space scope", "x-box-resource-id": "shuttle_path_entry_shared_space_scope_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMapping": { "description": "A standard representation of a shuttle path mapping. A path mapping\nconnects a source location on the migrated system to a destination in Box,\nor marks the source path as skipped.", "type": "object", "properties": { "id": { "description": "The unique identifier for the shuttle path mapping.", "type": "string", "example": "6a3ba7a24ea17bc9461eeacd" }, "type": { "description": "The value will always be `shuttle_path_mapping`.", "type": "string", "example": "shuttle_path_mapping", "enum": [ "shuttle_path_mapping" ] }, "job_id": { "description": "The unique identifier of the shuttle job this mapping belongs to.", "type": "string", "example": "6a3ba68e810d9156194530a1" }, "is_path_skipped": { "description": "Whether this source path is skipped during the migration.", "type": "boolean", "example": false }, "source": { "allOf": [ { "$ref": "#/components/schemas/ShuttlePathMappingLocation" }, { "description": "The source location being mapped." } ] }, "target": { "description": "The destination location. `null` when the source path is skipped or\nthe job has no destination, such as an analysis job.", "example": { "type": "account", "path": "/HR Migration", "path_id": "1234567890", "account": { "id": "123456", "email": "admin@company.box.com", "name": "Box Admin" }, "is_directory": true }, "oneOf": [ { "$ref": "#/components/schemas/ShuttlePathMappingLocation" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] } }, "required": [ "id", "type", "job_id", "is_path_skipped", "source" ], "title": "Shuttle path mapping", "x-box-resource-id": "shuttle_path_mapping_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappingAccount": { "description": "The account that owns an account-scoped path mapping location.", "type": "object", "properties": { "id": { "description": "The platform-native identifier of the account. `null` when the system\ndoes not provide one.", "type": "string", "example": "123456", "nullable": true }, "email": { "description": "The email address of the account. `null` when unknown.", "type": "string", "example": "admin@company.box.com", "nullable": true }, "name": { "description": "The display name of the account. `null` when unknown.", "type": "string", "example": "Box Admin", "nullable": true } }, "title": "Shuttle path mapping account", "x-box-resource-id": "shuttle_path_mapping_account_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappingAccountInput": { "description": "The account that owns an account-scoped path mapping location. Provide at\nleast one of `id` or `email`.", "type": "object", "properties": { "id": { "description": "The platform-native identifier of the account.", "type": "string", "example": "123456" }, "email": { "description": "The email address of the account.", "type": "string", "example": "admin@company.box.com" } }, "additionalProperties": false, "minProperties": 1, "title": "Shuttle path mapping account input", "x-box-resource-id": "shuttle_path_mapping_account_input_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappingAccountLocation": { "description": "A path mapping location scoped to a user or service account.", "type": "object", "properties": { "type": { "description": "The value will always be `account`.", "type": "string", "example": "account", "enum": [ "account" ] }, "path": { "description": "The human-readable path relative to the account root.", "type": "string", "example": "/HR Migration" }, "path_id": { "description": "The stable identifier of the location. `null` when the system does not\nprovide one.", "type": "string", "example": "1234567890", "nullable": true }, "account": { "allOf": [ { "$ref": "#/components/schemas/ShuttlePathMappingAccount" }, { "description": "The account that owns this location." } ] }, "is_directory": { "description": "Whether the location is a directory. `null` when unknown.", "type": "boolean", "example": true, "nullable": true } }, "required": [ "type", "path" ], "title": "Shuttle path mapping account location", "x-box-resource-id": "shuttle_path_mapping_account_location_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappingAccountLocationInput": { "description": "An account-scoped source location supplied when creating or updating a path\nmapping.", "type": "object", "properties": { "type": { "description": "The value will always be `account`.", "type": "string", "example": "account", "enum": [ "account" ] }, "path": { "description": "The human-readable path relative to the account root.", "type": "string", "example": "/Shared Documents", "minLength": 1 }, "path_id": { "description": "An optional stable identifier of the location, when obtained from\nbrowsing.", "type": "string", "example": "sp-folder-001" }, "account": { "allOf": [ { "$ref": "#/components/schemas/ShuttlePathMappingAccountInput" }, { "description": "The account that owns this location. Provide at least one of `id`\nor `email`." } ] }, "is_directory": { "description": "Whether the location is a directory. When set, the destination must be\nthe same kind of object.", "type": "boolean", "example": true } }, "required": [ "type", "path", "account" ], "title": "Shuttle path mapping account location input", "x-box-resource-id": "shuttle_path_mapping_account_location_input_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappingAccountLocationTargetInput": { "description": "An account-scoped destination location supplied when creating or updating a\npath mapping.", "type": "object", "properties": { "type": { "description": "The value will always be `account`.", "type": "string", "example": "account", "enum": [ "account" ] }, "path": { "description": "The human-readable path relative to the account root.", "type": "string", "example": "/HR Migration", "minLength": 1 }, "path_id": { "description": "An optional stable identifier of the location, when obtained from\nbrowsing.", "type": "string", "example": "1234567890" }, "account": { "allOf": [ { "$ref": "#/components/schemas/ShuttlePathMappingAccountInput" }, { "description": "The account that owns this location. Provide at least one of `id`\nor `email`." } ] } }, "required": [ "type", "path", "account" ], "title": "Shuttle path mapping account location target input", "x-box-resource-id": "shuttle_path_mapping_account_location_target_input_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappingCreateRequest": { "description": "The request body used to create a new shuttle path mapping.", "type": "object", "properties": { "job_id": { "description": "The unique identifier of the shuttle job this mapping belongs to.", "type": "string", "example": "6a3ba68e810d9156194530a1" }, "is_path_skipped": { "description": "Whether this source path should be skipped during the migration.\nDefaults to `false`.", "type": "boolean", "example": false, "default": false }, "source": { "allOf": [ { "$ref": "#/components/schemas/ShuttlePathMappingLocationInput" }, { "description": "The source location to migrate from." } ] }, "target": { "description": "The destination location to migrate to. Omit or set to `null` when the\nsource path is skipped.", "example": { "type": "account", "path": "/HR Migration", "account": { "email": "admin@company.box.com" } }, "oneOf": [ { "$ref": "#/components/schemas/ShuttlePathMappingTargetLocationInput" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] } }, "required": [ "job_id", "source" ], "title": "Shuttle path mapping create request", "x-box-resource-id": "shuttle_path_mapping_create_request_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappingImportCreateRequest": { "description": "The request body used to import a shuttle job's path mappings from a\nspreadsheet already stored in Box.", "type": "object", "properties": { "job_id": { "description": "The unique identifier of the shuttle job whose path mappings are\nreplaced.", "type": "string", "example": "6a3ba68e810d9156194530a1" }, "file_id": { "description": "The unique identifier of the Box file holding the mapping workbook. The\nfile is read as the calling user, so it must live somewhere that user can\ndownload from.", "type": "string", "example": "12345678901" } }, "required": [ "job_id", "file_id" ], "title": "Shuttle path mapping import create request", "x-box-resource-id": "shuttle_path_mapping_import_create_request_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappingLocation": { "description": "One side of a path mapping. The object shape is determined by `type`.", "oneOf": [ { "$ref": "#/components/schemas/ShuttlePathMappingAccountLocation" }, { "$ref": "#/components/schemas/ShuttlePathMappingSharedSpaceLocation" } ], "title": "Shuttle path mapping location", "x-box-resource-id": "shuttle_path_mapping_location_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappingLocationInput": { "description": "A source location supplied when creating or updating a path mapping. The\nobject shape is determined by `type`.", "oneOf": [ { "$ref": "#/components/schemas/ShuttlePathMappingAccountLocationInput" }, { "$ref": "#/components/schemas/ShuttlePathMappingSharedSpaceLocationInput" } ], "title": "Shuttle path mapping location input", "x-box-resource-id": "shuttle_path_mapping_location_input_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappings": { "description": "A paginated list of shuttle path mappings.", "type": "object", "allOf": [ { "required": [ "entries" ], "properties": { "entries": { "description": "A list of shuttle path mappings.", "type": "array", "items": { "$ref": "#/components/schemas/ShuttlePathMapping" } } } }, { "type": "object", "description": "The part of an API response that describes marker\nbased pagination.", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } } ], "title": "Shuttle path mappings", "x-box-resource-id": "shuttle_path_mappings_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappingSharedSpaceLocation": { "description": "A path mapping location scoped to a shared container such as a site, team\ndrive, bucket, or file share.", "type": "object", "properties": { "type": { "description": "The value will always be `shared_space`.", "type": "string", "example": "shared_space", "enum": [ "shared_space" ] }, "space": { "description": "The display name of the shared container. `null` when the system has a\nsingle implicit container.", "type": "string", "example": "HR Team Site", "nullable": true }, "path": { "description": "The human-readable path relative to the shared container.", "type": "string", "example": "/Shared Documents" }, "path_id": { "description": "The stable identifier of the location. `null` when the system does not\nprovide one.", "type": "string", "example": "sp-folder-001", "nullable": true }, "is_directory": { "description": "Whether the location is a directory. `null` when unknown.", "type": "boolean", "example": true, "nullable": true } }, "required": [ "type", "path" ], "title": "Shuttle path mapping shared space location", "x-box-resource-id": "shuttle_path_mapping_shared_space_location_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappingSharedSpaceLocationInput": { "description": "A shared-container source location supplied when creating or updating a\npath mapping.", "type": "object", "properties": { "type": { "description": "The value will always be `shared_space`.", "type": "string", "example": "shared_space", "enum": [ "shared_space" ] }, "space": { "description": "The display name of the shared container. Required for systems with\nmultiple containers.", "type": "string", "example": "HR Team Site" }, "path": { "description": "The human-readable path relative to the shared container.", "type": "string", "example": "/Shared Documents", "minLength": 1 }, "path_id": { "description": "An optional stable identifier of the location, when obtained from\nbrowsing.", "type": "string", "example": "sp-folder-001" }, "is_directory": { "description": "Whether the location is a directory. When set, the destination must be\nthe same kind of object.", "type": "boolean", "example": true } }, "required": [ "type", "path" ], "title": "Shuttle path mapping shared space location input", "x-box-resource-id": "shuttle_path_mapping_shared_space_location_input_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappingSharedSpaceLocationTargetInput": { "description": "A shared-container destination location supplied when creating or updating\na path mapping.", "type": "object", "properties": { "type": { "description": "The value will always be `shared_space`.", "type": "string", "example": "shared_space", "enum": [ "shared_space" ] }, "space": { "description": "The display name of the shared container. Required for systems with\nmultiple containers.", "type": "string", "example": "HR Team Site" }, "path": { "description": "The human-readable path relative to the shared container.", "type": "string", "example": "/HR Migration", "minLength": 1 }, "path_id": { "description": "An optional stable identifier of the location, when obtained from\nbrowsing.", "type": "string", "example": "1234567890" } }, "required": [ "type", "path" ], "title": "Shuttle path mapping shared space location target input", "x-box-resource-id": "shuttle_path_mapping_shared_space_location_target_input_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappingTargetLocationInput": { "description": "A destination location supplied when creating or updating a path mapping.\nThe object shape is determined by `type`. Destination input does not\ninclude `is_directory`; that flag is taken from the source.", "oneOf": [ { "$ref": "#/components/schemas/ShuttlePathMappingAccountLocationTargetInput" }, { "$ref": "#/components/schemas/ShuttlePathMappingSharedSpaceLocationTargetInput" } ], "title": "Shuttle path mapping target location input", "x-box-resource-id": "shuttle_path_mapping_target_location_input_v2026.0", "x-box-tag": "shuttle" }, "ShuttlePathMappingUpdateRequest": { "description": "The request body used to update an existing shuttle path mapping. Only the\nfields supplied in the request body are changed. `job_id`, `id`, and `type`\nare immutable.", "type": "object", "properties": { "is_path_skipped": { "description": "Whether this source path should be skipped during the migration.", "type": "boolean", "example": true }, "source": { "allOf": [ { "$ref": "#/components/schemas/ShuttlePathMappingLocationInput" }, { "description": "The source location to migrate from." } ] }, "target": { "description": "The destination location to migrate to. Set to `null` to clear the\ndestination, for example when skipping the source path.", "example": { "type": "account", "path": "/HR Migration", "account": { "email": "admin@company.box.com" } }, "oneOf": [ { "$ref": "#/components/schemas/ShuttlePathMappingTargetLocationInput" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] } }, "minProperties": 1, "title": "Shuttle path mapping update request", "x-box-resource-id": "shuttle_path_mapping_update_request_v2026.0", "x-box-tag": "shuttle" }, "ShuttleReport": { "description": "A report generated asynchronously for a shuttle job run. Keep polling\nwhile `status` is `pending` or `processing`. Stop when `status` is\n`complete`, `failed`, `canceled`, or `unknown`. The generated Box file\nor folder is `null` until generation finishes.", "type": "object", "properties": { "id": { "description": "The unique identifier for the shuttle report.", "type": "string", "example": "6a3ba8d14f2c91e8370b4d12" }, "type": { "description": "The value will always be `shuttle_report`.", "type": "string", "example": "shuttle_report", "enum": [ "shuttle_report" ] }, "run_id": { "description": "The unique identifier of the shuttle run this report was generated\nfor.", "type": "string", "example": "6a3ba68e810d9156194530a1:42" }, "status": { "description": "The generation status of the report. This is an open string whose set\nof values is expected to grow; the currently documented values include\n`pending`, `processing`, `complete`, `failed`, `canceled`, and\n`unknown`. Keep polling `pending` and `processing`. Stop on\n`complete`, `failed`, `canceled`, and `unknown`. Treat any value that\nis not recognized the same as `unknown`: do not fail parsing, and do\nnot keep polling.", "type": "string", "example": "complete" }, "format": { "description": "The output file format of the report.", "type": "string", "example": "xlsx", "enum": [ "xlsx", "csv" ] }, "sections": { "description": "The sections included in the report. Echoes the sections requested on\ncreate. This is an open list whose set of values is expected to grow;\nthe currently documented values include `files_and_folders`,\n`event_log`, `transfer_overview`, `source_users`, `target_users`,\n`source_collaborators`, `target_collaborators`,\n`source_collaborations`, and `target_collaborations`. Omitted on\nolder reports that have no stored section list. New reports always\ninclude this field.", "type": "array", "items": { "type": "string", "description": "A section included in the report.", "example": "event_log" }, "example": [ "event_log", "transfer_overview" ], "minItems": 1 }, "users_scope": { "description": "Which users are included in user-related report sections.", "type": "string", "example": "migrated", "enum": [ "migrated", "all" ] }, "output": { "description": "The generated Box file or folder. Always present; `null` until\n`status` is `complete`.", "example": { "id": "12345678", "type": "file" }, "oneOf": [ { "$ref": "#/components/schemas/ShuttleReportOutput" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] }, "created_at": { "description": "When report generation was requested.", "type": "string", "format": "date-time", "example": "2026-03-15T06:35:00Z" }, "completed_at": { "description": "When report generation finished. Always present; `null` while\ngeneration is still in progress.", "type": "string", "format": "date-time", "example": "2026-03-15T06:36:12Z", "nullable": true } }, "required": [ "id", "type", "run_id", "status", "format", "output", "completed_at" ], "title": "Shuttle report", "x-box-resource-id": "shuttle_report_v2026.0", "x-box-tag": "shuttle" }, "ShuttleReportCreateRequest": { "description": "The request body used to generate a report for a shuttle run. Generation\nis asynchronous: the created report is returned immediately in `pending`\nor `processing` status. Poll `GET /shuttle_reports/{shuttle_report_id}`\nwhile `status` is `pending` or `processing`. Stop when `status` is\n`complete`, `failed`, `canceled`, or `unknown`. Repeating this request\nwith the same parameters reuses the existing report instead of creating\na duplicate.", "type": "object", "properties": { "run_id": { "description": "The unique identifier of the shuttle run to generate a report for.", "type": "string", "example": "6a3ba68e810d9156194530a1:42" }, "format": { "description": "The output file format of the report.", "type": "string", "example": "xlsx", "enum": [ "xlsx", "csv" ] }, "sections": { "description": "The sections to include in the report. Must be a non-empty subset of\nthe run's `available_report_sections`. This is an open list whose set\nof values is expected to grow; the currently documented values include\n`files_and_folders`, `event_log`, `transfer_overview`, `source_users`,\n`target_users`, `source_collaborators`, `target_collaborators`,\n`source_collaborations`, and `target_collaborations`.", "type": "array", "items": { "type": "string", "description": "A section to include in the report.", "example": "event_log" }, "example": [ "event_log", "transfer_overview" ], "minItems": 1 }, "users_scope": { "description": "Which users to include in user-related report sections. Defaults to\n`migrated` when omitted.", "type": "string", "example": "migrated", "default": "migrated", "enum": [ "migrated", "all" ] } }, "required": [ "run_id", "format", "sections" ], "title": "Shuttle report create request", "x-box-resource-id": "shuttle_report_create_request_v2026.0", "x-box-tag": "shuttle" }, "ShuttleReportOutput": { "description": "A reference to the generated Box file or folder.", "type": "object", "properties": { "id": { "description": "The unique identifier of the generated Box file or folder.", "type": "string", "example": "12345678" }, "type": { "description": "The Box object type of the generated file or folder.", "type": "string", "example": "file", "enum": [ "file", "folder" ] } }, "required": [ "id", "type" ], "title": "Shuttle report output", "x-box-resource-id": "shuttle_report_output_v2026.0", "x-box-tag": "shuttle" }, "ShuttleReports": { "description": "A paginated list of shuttle reports.", "type": "object", "allOf": [ { "required": [ "entries" ], "properties": { "entries": { "description": "A list of shuttle reports.", "type": "array", "items": { "$ref": "#/components/schemas/ShuttleReport" } } } }, { "type": "object", "description": "The part of an API response that describes marker\nbased pagination.", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } } ], "title": "Shuttle reports", "x-box-resource-id": "shuttle_reports_v2026.0", "x-box-tag": "shuttle" }, "ShuttleRun": { "description": "A historical instance of a shuttle job run. A run is created each time\na job is started. Run IDs have the form `{job_id}:{run_number}`.", "type": "object", "properties": { "id": { "description": "The unique identifier for the shuttle run, in the form\n`{job_id}:{run_number}`.", "type": "string", "example": "6a3ba68e810d9156194530a1:42" }, "type": { "description": "The value will always be `shuttle_run`.", "type": "string", "example": "shuttle_run", "enum": [ "shuttle_run" ] }, "job_id": { "description": "The unique identifier of the shuttle job this run belongs to.", "type": "string", "example": "6a3ba68e810d9156194530a1" }, "run_mode": { "description": "The mode the run was started in. This is an open string whose set of\nvalues is expected to grow; the currently documented values include\n`transfer`, `simulation`, `analysis`, `scan`, and `unknown`. Clients\nshould treat any value they do not recognize as `unknown`.", "type": "string", "example": "transfer" }, "state": { "description": "The current state of the shuttle run. This is an open string whose set\nof values is expected to grow; the currently documented values include\n`running`, `stopping`, `completed`, `completed_with_errors`, `stopped`,\n`failed`, `timed_out`, and `unknown`. Clients should treat any value\nthey do not recognize as `unknown`.", "type": "string", "example": "completed" }, "started_at": { "description": "When the run started.", "type": "string", "format": "date-time", "example": "2026-03-15T02:00:00Z" }, "ended_at": { "description": "When the run ended. `null` while the run is still in progress.", "type": "string", "format": "date-time", "example": "2026-03-15T06:30:00Z", "nullable": true }, "duration_seconds": { "description": "Total duration of the run in seconds. `null` while the run is still in\nprogress.", "type": "integer", "format": "int64", "example": 16200, "nullable": true }, "stats": { "description": "Transfer statistics collected during the run.", "type": "object", "properties": { "bytes_sent": { "description": "Bytes transferred during the run.", "type": "integer", "format": "int64", "example": 1073741824 }, "files_sent": { "description": "Files transferred during the run.", "type": "integer", "format": "int64", "example": 4200 }, "folders_created": { "description": "Folders created on the destination during the run.", "type": "integer", "format": "int64", "example": 350 }, "is_estimated": { "description": "Whether these figures are estimates rather than final counts.", "type": "boolean", "example": false } }, "x-box-tag": "shuttle" }, "created_by": { "description": "The user who started the run. `null` for schedule- or system-initiated\nruns.", "example": { "id": "11446498", "type": "user" }, "oneOf": [ { "$ref": "#/components/schemas/User--Base" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] }, "available_report_sections": { "description": "Report sections that can be requested for this run. This is an open\nlist whose set of values is expected to grow; the currently documented\nvalues include `files_and_folders`, `event_log`, `transfer_overview`,\n`source_users`, `target_users`, `source_collaborators`,\n`target_collaborators`, `source_collaborations`, and\n`target_collaborations`.", "type": "array", "items": { "type": "string", "description": "A report section available for this run.", "example": "event_log" }, "example": [ "event_log", "files_and_folders" ] } }, "required": [ "id", "type", "job_id", "run_mode", "state" ], "title": "Shuttle run", "x-box-resource-id": "shuttle_run_v2026.0", "x-box-tag": "shuttle" }, "ShuttleRuns": { "description": "A paginated list of shuttle runs.", "type": "object", "allOf": [ { "required": [ "entries" ], "properties": { "entries": { "description": "A list of shuttle runs.", "type": "array", "items": { "$ref": "#/components/schemas/ShuttleRun" } } } }, { "type": "object", "description": "The part of an API response that describes marker\nbased pagination.", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } } ], "title": "Shuttle runs", "x-box-resource-id": "shuttle_runs_v2026.0", "x-box-tag": "shuttle" }, "ShuttleSubject": { "description": "A subject discovered on the source migration system, such as a user or\ngroup.", "type": "object", "properties": { "type": { "description": "Whether this subject is a user or a group.", "type": "string", "example": "user", "enum": [ "user", "group" ] }, "id": { "description": "The platform-native identifier of the subject. `null` when the system\ndoes not provide one.", "type": "string", "example": "sp-user-001", "nullable": true }, "email": { "description": "The email address of the subject. `null` when unknown.", "type": "string", "example": "user@example.com", "nullable": true }, "name": { "description": "The display name of the subject. `null` when unknown.", "type": "string", "example": "Jane Doe", "nullable": true }, "roles": { "description": "Roles this subject holds on the source. `null` when no roles are known.", "type": "array", "items": { "$ref": "#/components/schemas/ShuttleSubjectRole" }, "example": [ "owner" ], "nullable": true } }, "required": [ "type" ], "title": "Shuttle subject", "x-box-resource-id": "shuttle_subject_v2026.0", "x-box-tag": "shuttle" }, "ShuttleSubjectMapping": { "description": "A standard representation of a shuttle subject mapping. A subject mapping\nconnects a discovered source subject to a Box user or group, or marks the\nsubject as skipped.", "type": "object", "properties": { "id": { "description": "The unique identifier for the shuttle subject mapping.", "type": "string", "example": "6a3ba7b12ea17bc9461eeace" }, "type": { "description": "The value will always be `shuttle_subject_mapping`.", "type": "string", "example": "shuttle_subject_mapping", "enum": [ "shuttle_subject_mapping" ] }, "job_id": { "description": "The unique identifier of the shuttle job this mapping belongs to.", "type": "string", "example": "6a3ba68e810d9156194530a1" }, "discovered_subject_id": { "description": "The unique identifier of the discovered subject this mapping applies to.\n`null` for legacy mappings created before this field was tracked.", "type": "string", "example": "6a3ba7c02ea17bc9461eeacf", "nullable": true }, "revision": { "description": "The discovery-requirements revision this mapping was resolved against.\n`null` for legacy mappings.", "type": "integer", "format": "int32", "example": 3, "nullable": true }, "is_subject_skipped": { "description": "Whether this subject is skipped during the migration.", "type": "boolean", "example": false }, "source": { "allOf": [ { "$ref": "#/components/schemas/ShuttleSubject" }, { "description": "The source subject being mapped." } ] }, "target": { "description": "The Box target subject. `null` when the subject is skipped or not yet\nassigned.", "example": { "type": "user", "id": "12345678", "email": "jane.doe@company.box.com", "name": "Jane Doe" }, "oneOf": [ { "$ref": "#/components/schemas/ShuttleTargetSubject" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] } }, "required": [ "id", "type", "job_id", "is_subject_skipped", "source" ], "title": "Shuttle subject mapping", "x-box-resource-id": "shuttle_subject_mapping_v2026.0", "x-box-tag": "shuttle" }, "ShuttleSubjectMappingCreateRequest": { "description": "The request body used to create a new shuttle subject mapping.", "type": "object", "properties": { "job_id": { "description": "The unique identifier of the shuttle job this mapping belongs to.", "type": "string", "example": "6a3ba68e810d9156194530a1" }, "discovered_subject_id": { "description": "The unique identifier of the discovered subject to map.", "type": "string", "example": "6a3ba7c02ea17bc9461eeacf" }, "revision": { "description": "The discovery-requirements revision to resolve against. Omit to use the\nlatest revision.", "type": "integer", "format": "int32", "example": 3 }, "is_subject_skipped": { "description": "Whether this subject should be skipped during the migration. Defaults\nto `false`.", "type": "boolean", "example": false, "default": false }, "target": { "description": "The Box target to map to. Omit or set to `null` when the subject is\nskipped.", "example": { "type": "user", "id": "12345678" }, "oneOf": [ { "$ref": "#/components/schemas/ShuttleTargetSubjectInput" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] } }, "required": [ "job_id", "discovered_subject_id" ], "title": "Shuttle subject mapping create request", "x-box-resource-id": "shuttle_subject_mapping_create_request_v2026.0", "x-box-tag": "shuttle" }, "ShuttleSubjectMappingImportCreateRequest": { "description": "The request body used to import a shuttle job's subject mappings from a\nspreadsheet already stored in Box.", "type": "object", "properties": { "job_id": { "description": "The unique identifier of the shuttle job whose subject mappings are\nreplaced.", "type": "string", "example": "6a3ba68e810d9156194530a1" }, "file_id": { "description": "The unique identifier of the Box file holding the mapping workbook. The\nfile is read as the calling user, so it must live somewhere that user can\ndownload from.", "type": "string", "example": "12345678901" } }, "required": [ "job_id", "file_id" ], "title": "Shuttle subject mapping import create request", "x-box-resource-id": "shuttle_subject_mapping_import_create_request_v2026.0", "x-box-tag": "shuttle" }, "ShuttleSubjectMappings": { "description": "A paginated list of shuttle subject mappings.", "type": "object", "allOf": [ { "required": [ "entries" ], "properties": { "entries": { "description": "A list of shuttle subject mappings.", "type": "array", "items": { "$ref": "#/components/schemas/ShuttleSubjectMapping" } } } }, { "type": "object", "description": "The part of an API response that describes marker\nbased pagination.", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } } ], "title": "Shuttle subject mappings", "x-box-resource-id": "shuttle_subject_mappings_v2026.0", "x-box-tag": "shuttle" }, "ShuttleSubjectMappingUpdateRequest": { "description": "The request body used to update an existing shuttle subject mapping. Only\nthe fields supplied in the request body are changed. `job_id`, `id`,\n`type`, `source`, `discovered_subject_id`, and `revision` are immutable.", "type": "object", "properties": { "is_subject_skipped": { "description": "Whether this subject should be skipped during the migration.", "type": "boolean", "example": true }, "target": { "description": "The Box target to map to. Set to `null` only for a skipped subject.\nSetting it to `null` while the mapping is active fails validation.\nUpdating `is_subject_skipped` alone preserves the existing target.", "example": { "type": "user", "id": "12345678" }, "oneOf": [ { "$ref": "#/components/schemas/ShuttleTargetSubjectInput" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] } }, "minProperties": 1, "title": "Shuttle subject mapping update request", "x-box-resource-id": "shuttle_subject_mapping_update_request_v2026.0", "x-box-tag": "shuttle" }, "ShuttleSubjectRole": { "description": "A role a source subject holds on the source system.", "type": "string", "example": "owner", "enum": [ "owner", "creator", "updater", "namespace_account", "sharee", "account_holder", "unknown" ], "title": "Shuttle subject role", "x-box-tag": "shuttle" }, "ShuttleSystem": { "description": "A standard representation of a shuttle system. A shuttle system describes a\nsource or destination that Shuttle can migrate content to or from, along\nwith its current connection state.", "type": "object", "properties": { "id": { "description": "The unique identifier for the shuttle system.", "type": "string", "example": "6a315c0754833bfc5df067bf" }, "type": { "description": "The value will always be `shuttle_system`.", "type": "string", "example": "shuttle_system", "enum": [ "shuttle_system" ] }, "name": { "description": "The display name of the shuttle system.", "type": "string", "example": "BoxProd" }, "system_type": { "description": "Identifies the kind of source or destination this system represents, for\nexample `box`, `windows`, `sharepoint`, or `amazon_s3`. New system types\nare added over time, so clients must tolerate values they do not\nrecognize rather than treating this as a fixed set.", "type": "string", "example": "box" }, "label": { "description": "A server-computed display label for the system.", "type": "string", "example": "Box (Production)" }, "state": { "description": "The current connection state of the shuttle system.", "type": "string", "example": "connected", "enum": [ "connected", "disconnected", "unknown" ] } }, "required": [ "id", "type", "name", "system_type", "state" ], "title": "Shuttle system", "x-box-resource-id": "shuttle_system_v2026.0", "x-box-tag": "shuttle" }, "ShuttleSystemCreateRequest": { "description": "The request body for creating a shuttle system. Only Windows agent systems\ncan be created through the public API, so `system_type` must be `windows`.", "type": "object", "properties": { "name": { "description": "The display name for the new shuttle system.", "type": "string", "example": "NYC File Server", "minLength": 1 }, "system_type": { "description": "The public system type identifier for the new shuttle system. Only\n`windows` is currently supported through the public API.", "type": "string", "example": "windows", "enum": [ "windows" ] } }, "required": [ "name", "system_type" ], "title": "Shuttle system create request", "x-box-resource-id": "shuttle_system_create_request_v2026.0", "x-box-tag": "shuttle" }, "ShuttleSystems": { "description": "A paginated list of shuttle systems.", "type": "object", "allOf": [ { "required": [ "entries" ], "properties": { "entries": { "description": "A list of shuttle systems.", "type": "array", "items": { "$ref": "#/components/schemas/ShuttleSystem" } } } }, { "type": "object", "description": "The part of an API response that describes marker\nbased pagination.", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } } ], "title": "Shuttle systems", "x-box-resource-id": "shuttle_systems_v2026.0", "x-box-tag": "shuttle" }, "ShuttleSystemUpdateRequest": { "description": "The request body for updating a shuttle system. Only the fields supplied are\nchanged.", "type": "object", "properties": { "name": { "description": "The updated display name for the shuttle system.", "type": "string", "example": "NYC File Server (Primary)", "minLength": 1 } }, "minProperties": 1, "title": "Shuttle system update request", "x-box-resource-id": "shuttle_system_update_request_v2026.0", "x-box-tag": "shuttle" }, "ShuttleTargetSubject": { "description": "A Box user or group that a source subject is mapped to.", "type": "object", "properties": { "type": { "description": "Whether the Box target is a user or a group.", "type": "string", "example": "user", "enum": [ "user", "group" ] }, "id": { "description": "The Box user or group ID. `null` when the mapping was not created\nthrough this API and is identified by email (user) or name (group)\ninstead. Skip is represented by `target: null`, not a missing `id`.\nCreate and update always send `id`.", "type": "string", "example": "12345678", "nullable": true }, "email": { "description": "The email address of the target. `null` when unknown.", "type": "string", "example": "user@example.com", "nullable": true }, "name": { "description": "The display name of the target. `null` when unknown.", "type": "string", "example": "Jane Doe", "nullable": true } }, "required": [ "type" ], "title": "Shuttle target subject", "x-box-resource-id": "shuttle_target_subject_v2026.0", "x-box-tag": "shuttle" }, "ShuttleTargetSubjectInput": { "description": "A Box user or group to map a source subject to.", "type": "object", "properties": { "type": { "description": "Whether the Box target is a user or a group.", "type": "string", "example": "user", "enum": [ "user", "group" ] }, "id": { "description": "The identifier of the target Box subject.", "type": "string", "example": "12345678" } }, "required": [ "type", "id" ], "title": "Shuttle target subject input", "x-box-resource-id": "shuttle_target_subject_input_v2026.0", "x-box-tag": "shuttle" }, "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": "Document Split", "description": "A set of endpoints used to split a paginated source document into multiple\nfiles based on user-defined or AI-generated page ranges.", "x-box-tag": "document_split" }, { "name": "Query", "description": "Query for your items.", "x-box-tag": "query" }, { "name": "Shuttle", "description": "Endpoints for managing Box Shuttle, the service that migrates content into\nBox from external sources. Use these endpoints to manage the systems that\nShuttle migrates content from and the migration jobs that Shuttle runs.", "x-box-tag": "shuttle" } ], "externalDocs": { "description": "Box Developer Documentation.", "url": "https://developer.box.com" } }