> ## Documentation Index > Fetch the complete documentation index at: https://developer.box.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Document Split job > Initiates a Document Split job for the supplied source file. The job runs asynchronously; clients can poll the returned job ID to track progress. All split-specific input lives under `split_input`. When `split_input.split_type` is `manual`, provide `split_input.split_definition` (continuous page ranges; `version` may be omitted or `v_1`). When `split_input.split_type` is `page_selection`, provide `split_input.page_selection` (non-linear page segments; `version` may be omitted or `v_2`). `split_input.prompt` must not be provided for either of those variants. When `split_input.split_type` is `smart`, `split_input.prompt` is required and neither `split_input.split_definition` nor `split_input.page_selection` must be provided. > [!NOTE] > > Learn more about [Box SDK versioning strategy](https://developer.box.com/guides/tooling/sdks/sdk-versioning.md). ## OpenAPI ````yaml box-openapi-v2026.0.json POST /document_splits 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: 0274a35f73 servers: - url: https://api.box.com/2.0 description: Box Platform API server. 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 files 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 Box from external sources. Use these endpoints to manage the systems that Shuttle migrates content from and the migration jobs that Shuttle runs. x-box-tag: shuttle externalDocs: description: Box Developer Documentation. url: https://developer.box.com paths: /document_splits: post: tags: - Document Split summary: Create Document Split job description: >- Initiates a Document Split job for the supplied source file. The job runs asynchronously; clients can poll the returned job ID to track progress. All split-specific input lives under `split_input`. When `split_input.split_type` is `manual`, provide `split_input.split_definition` (continuous page ranges; `version` may be omitted or `v_1`). When `split_input.split_type` is `page_selection`, provide `split_input.page_selection` (non-linear page segments; `version` may be omitted or `v_2`). `split_input.prompt` must not be provided for either of those variants. When `split_input.split_type` is `smart`, `split_input.prompt` is required and neither `split_input.split_definition` nor `split_input.page_selection` must be provided. operationId: post_document_splits_v2026.0 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 to 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 missing. content: application/json: schema: $ref: '#/components/schemas/ClientError' '401': description: >- Returned when the access token provided in the `Authorization` header is not recognized or not provided. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: >- Returned when the authenticated user does not have access to the Document Generation feature. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: >- Returned when the source file or destination folder cannot be found or 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 time. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' 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: DocumentSplitCreateRequest: description: >- The request body for creating a Document Split job. The `split_input` property carries the caller-supplied input that determines how the split is 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 traceability. 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. The value is returned on job responses for correlation only. It is not a Box resource ID, is not required to be unique, and cannot be used to look 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 DocumentSplitCreateResponse: description: >- A reference to a newly created Document Split job. Returned when a Document Split job is accepted for asynchronous processing. Clients can poll the full 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 ClientError: description: A generic error. type: object properties: type: description: The value will always be `error`. type: string example: error enum: - error nullable: false status: description: The HTTP status of the response. type: integer format: int32 example: 400 nullable: false code: description: A Box-specific error code. type: string example: item_name_invalid enum: - created - accepted - no_content - redirect - not_modified - bad_request - unauthorized - forbidden - not_found - method_not_allowed - conflict - precondition_failed - too_many_requests - internal_server_error - unavailable - item_name_invalid - insufficient_scope message: description: A short message describing the error. type: string example: Method Not Allowed nullable: false context_info: description: >- A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example. type: object example: message: Something went wrong additionalProperties: {} nullable: true help_url: description: A URL that links to more information about why this error occurred. type: string example: >- https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/ nullable: false request_id: description: >- A unique identifier for this response, which can be used when contacting Box support. type: string example: abcdef123456 nullable: false title: Client error x-box-resource-id: client_error_v2026.0 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 DocumentSplitCreateRequestManual: description: >- Validation rules for creating a Document Split job using caller-supplied page ranges. 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 legacy `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 containing 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 selections. Each item produces one output file from the declared page segments. 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 must 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 ranges 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 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 in the array produces one output PDF assembled from the declared page segments. 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 produces 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 system 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 segment 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 DocumentSplitPageSelectionSegment: description: >- A single page segment within a page selection item. The `type` field identifies 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 document. 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 DocumentSplitPageSelectionPageRange: description: >- A page selection segment that includes an inclusive page range from the source 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 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 ````