diff --git a/openapi.json b/openapi.json index 580bd2c4..0e76798a 100644 --- a/openapi.json +++ b/openapi.json @@ -14,7 +14,7 @@ "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "2024.0", - "x-box-commit-hash": "56657ab895" + "x-box-commit-hash": "53bdced3cd" }, "servers": [ { @@ -680,6 +680,16 @@ "example": true } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } }, @@ -5451,6 +5461,16 @@ "example": true } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } }, @@ -11736,6 +11756,9 @@ "can_preview": true, "can_download": true, "can_edit": true + }, + "one_time_passcode": { + "mode": "none" } } } @@ -11875,6 +11898,16 @@ "example": true } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } } @@ -11913,6 +11946,9 @@ "can_preview": true, "can_download": true, "can_edit": true + }, + "one_time_passcode": { + "mode": "none" } } } @@ -12082,6 +12118,16 @@ "example": true } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } } @@ -12120,6 +12166,9 @@ "can_preview": true, "can_download": true, "can_edit": true + }, + "one_time_passcode": { + "mode": "none" } } } @@ -12471,6 +12520,9 @@ "can_preview": true, "can_download": true, "can_edit": false + }, + "one_time_passcode": { + "mode": "none" } } } @@ -12611,6 +12663,16 @@ "example": false } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } } @@ -12649,6 +12711,9 @@ "can_preview": true, "can_download": true, "can_edit": false + }, + "one_time_passcode": { + "mode": "none" } } } @@ -12818,6 +12883,16 @@ "example": false } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } } @@ -12856,6 +12931,9 @@ "can_preview": true, "can_download": true, "can_edit": false + }, + "one_time_passcode": { + "mode": "none" } } } @@ -13421,6 +13499,16 @@ "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } } @@ -13745,6 +13833,9 @@ "can_preview": true, "can_download": true, "can_edit": false + }, + "one_time_passcode": { + "mode": "none" } } } @@ -13884,6 +13975,16 @@ "example": false } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } } @@ -13922,6 +14023,9 @@ "can_preview": true, "can_download": true, "can_edit": false + }, + "one_time_passcode": { + "mode": "none" } } } @@ -14091,6 +14195,16 @@ "example": true } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } } @@ -14129,6 +14243,9 @@ "can_preview": true, "can_download": true, "can_edit": false + }, + "one_time_passcode": { + "mode": "none" } } } @@ -15172,7 +15289,7 @@ "delete": { "operationId": "delete_users_id", "summary": "Delete user", - "description": "Deletes a user. By default, this operation fails if the user\nstill owns any content. \nTo proceed, move their owned content first, or use the `force` parameter to delete\nthe user and their files.", + "description": "Deletes a user. By default, this operation fails if the user\nstill owns any content. \nTo proceed, move their owned content first, or use the `force` parameter to delete\nthe user and their files.\n\nIf the enterprise has a retention policy, including a retired one, or a\nlegal hold that is not fully released, you can't delete a user who owns\ncontent, even with `force`. Transfer the user's content first by using the\n[Transfer owned folders](https://developer.box.com/reference/put-users-id-folders-0)\nendpoint.", "parameters": [ { "name": "user_id", @@ -15196,7 +15313,7 @@ { "name": "force", "in": "query", - "description": "Specifies whether to delete the user even if they still own files.", + "description": "Specifies whether to delete the user even if they still own files.\n\nIf the user owns content and the enterprise has a retention policy,\nincluding a retired one, or a legal hold that is not fully released,\nsetting `force` to `true` doesn't delete the user. The request returns\na `403` error, and you must transfer the user's content before deleting\nthe user.", "schema": { "type": "boolean" }, @@ -15207,6 +15324,16 @@ "204": { "description": "Removes the user and returns an empty response." }, + "403": { + "description": "Returns an error if the user can't be deleted.\n\n* `forbidden` with the message\n `User cannot be deleted due to retention policies. Please transfer user content first`\n when the user owns content and the enterprise has a retention policy,\n including a retired one, or a legal hold that is not fully released. This applies\n even if none of the policies apply to the user's content, and even\n when `force` is set to `true`. Transfer the user's content by using the\n [Transfer owned folders](https://developer.box.com/reference/put-users-id-folders-0)\n endpoint, then try again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, "default": { "description": "An unexpected client error.", "content": { @@ -31336,7 +31463,8 @@ "effective_permission", "is_password_enabled", "download_count", - "preview_count" + "preview_count", + "one_time_passcode" ], "properties": { "url": { @@ -31454,6 +31582,57 @@ "type": "integer", "example": 3, "nullable": false + }, + "one_time_passcode": { + "allOf": [ + { + "title": "Shared link OTP settings", + "description": "One-time-passcode (OTP) settings for a shared link. When OTP enforcement\nis enabled, anonymous users must verify their identity via a\none-time-passcode emailed to them before the shared link will grant\naccess.\n\nOTP can only be used with shared links that have an `access` level of\n`open`. Password protection and OTP cannot be enabled at the same time.", + "type": "object", + "required": [ + "mode" + ], + "properties": { + "mode": { + "description": "The current OTP enforcement mode for the shared link.\n\n* `none` - OTP enforcement is turned off. The shared link is accessible\n without any one-time-passcode verification.\n* `open` - Any anonymous recipient can request a one-time-passcode to\n any email address and access the shared link after verifying it.\n Collaborators and registered Box users access the link without\n being prompted.\n* `allowlist` - Anonymous recipients can request a one-time-passcode\n only when they enter an email that matches an entry on the\n `allowlist`.", + "type": "string", + "example": "allowlist" + }, + "allowlist": { + "description": "The list of email and domain entries that are permitted to access the\nshared link when `mode` is `allowlist`. Anonymous users whose\nemail matches an entry can request and verify a one-time-passcode.\n\nBecause the entries carry recipient email addresses and the identity\nof the user who added them, this field is only returned to users\nwith owner, co-owner, or editor access on the item. For viewer\ncollaborators and below the field is omitted.\n\nAn allowlist contains at most 1000 entries, matching the limit\nenforced when setting the allowlist on a shared link.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SharedLinkOtpAllowlistEntry" + }, + "example": [ + { + "type": "email", + "value": "alice@example.com", + "created_at": "2026-05-19T12:00:00Z", + "created_by": { + "id": "11446498", + "type": "user" + } + }, + { + "type": "domain", + "value": "example.com", + "created_at": "2026-05-19T12:00:00Z", + "created_by": { + "id": "11446498", + "type": "user" + } + } + ], + "maxItems": 1000 + } + } + }, + { + "description": "The one-time-passcode (OTP) settings for this shared link.\n\nThis field is always present. For links where OTP does not\napply (for example, shared links whose `access` is not `open`),\nthe object is returned with `mode` set to `none`." + } + ], + "nullable": false } } }, @@ -33208,7 +33387,8 @@ "effective_permission", "is_password_enabled", "download_count", - "preview_count" + "preview_count", + "one_time_passcode" ], "properties": { "url": { @@ -33326,6 +33506,57 @@ "type": "integer", "example": 3, "nullable": false + }, + "one_time_passcode": { + "allOf": [ + { + "title": "Shared link OTP settings", + "description": "One-time-passcode (OTP) settings for a shared link. When OTP enforcement\nis enabled, anonymous users must verify their identity via a\none-time-passcode emailed to them before the shared link will grant\naccess.\n\nOTP can only be used with shared links that have an `access` level of\n`open`. Password protection and OTP cannot be enabled at the same time.", + "type": "object", + "required": [ + "mode" + ], + "properties": { + "mode": { + "description": "The current OTP enforcement mode for the shared link.\n\n* `none` - OTP enforcement is turned off. The shared link is accessible\n without any one-time-passcode verification.\n* `open` - Any anonymous recipient can request a one-time-passcode to\n any email address and access the shared link after verifying it.\n Collaborators and registered Box users access the link without\n being prompted.\n* `allowlist` - Anonymous recipients can request a one-time-passcode\n only when they enter an email that matches an entry on the\n `allowlist`.", + "type": "string", + "example": "allowlist" + }, + "allowlist": { + "description": "The list of email and domain entries that are permitted to access the\nshared link when `mode` is `allowlist`. Anonymous users whose\nemail matches an entry can request and verify a one-time-passcode.\n\nBecause the entries carry recipient email addresses and the identity\nof the user who added them, this field is only returned to users\nwith owner, co-owner, or editor access on the item. For viewer\ncollaborators and below the field is omitted.\n\nAn allowlist contains at most 1000 entries, matching the limit\nenforced when setting the allowlist on a shared link.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SharedLinkOtpAllowlistEntry" + }, + "example": [ + { + "type": "email", + "value": "alice@example.com", + "created_at": "2026-05-19T12:00:00Z", + "created_by": { + "id": "11446498", + "type": "user" + } + }, + { + "type": "domain", + "value": "example.com", + "created_at": "2026-05-19T12:00:00Z", + "created_by": { + "id": "11446498", + "type": "user" + } + } + ], + "maxItems": 1000 + } + } + }, + { + "description": "The one-time-passcode (OTP) settings for this shared link.\n\nThis field is always present. For links where OTP does not\napply (for example, shared links whose `access` is not `open`),\nthe object is returned with `mode` set to `none`." + } + ], + "nullable": false } } }, @@ -35114,7 +35345,7 @@ ] }, "entries": { - "description": "An list of entries in the metadata card.", + "description": "A list of entries in the metadata card.", "type": "array", "items": { "type": "object", @@ -37671,6 +37902,162 @@ "x-box-resource-id": "session_termination", "x-box-tag": "session_termination" }, + "SharedLinkOtpAllowlistEntry": { + "description": "An entry on the OTP allowlist for a shared link. The entry can match\neither a specific email address or every email address that belongs to\na domain.", + "type": "object", + "properties": { + "type": { + "description": "The kind of allowlist entry.\n\n* `email` - The entry matches a single email address.\n* `domain` - The entry matches every email address under the\n given domain.", + "type": "string", + "example": "email", + "enum": [ + "email", + "domain" + ] + }, + "value": { + "description": "The value of the allowlist entry.\n\n* For `email` entries, the full email address (must contain `@`).\n* For `domain` entries, the bare domain (e.g. `example.com`).", + "type": "string", + "example": "alice@example.com" + }, + "created_at": { + "description": "The date and time when the allowlist entry was added.", + "type": "string", + "format": "date-time", + "example": "2026-05-19T12:00:00Z" + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "User who added this entry." + } + ] + } + }, + "required": [ + "type", + "value", + "created_at", + "created_by" + ], + "title": "Shared link OTP allowlist entry" + }, + "SharedLinkOtpAllowlistEntryWritable": { + "description": "An entry used to write the OTP allowlist for a shared link. The entry can\nmatch either a specific email address or every email address that\nbelongs to a domain.", + "type": "object", + "properties": { + "type": { + "description": "The kind of allowlist entry.\n\n* `email` - The entry matches a single email address.\n* `domain` - The entry matches every email address under the\n given domain.", + "type": "string", + "example": "email", + "enum": [ + "email", + "domain" + ] + }, + "value": { + "description": "The value of the allowlist entry.\n\n* For `email` entries, the full email address (must contain `@`).\n* For `domain` entries, the bare domain (e.g. `example.com`).", + "type": "string", + "example": "alice@example.com" + } + }, + "required": [ + "type", + "value" + ], + "title": "Shared link OTP allowlist entry (Write)" + }, + "SharedLinkOtpWritable": { + "description": "One-time-passcode (OTP) settings for a shared link. When OTP enforcement\nis enabled, anonymous users must verify their identity via a\none-time-passcode emailed to them before the shared link will grant\naccess.\n\nOTP can only be used with shared links that have an `access` level of\n`open`. Password protection and OTP cannot be enabled at the same time.", + "oneOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritableNone" + }, + { + "$ref": "#/components/schemas/SharedLinkOtpWritableOpen" + }, + { + "$ref": "#/components/schemas/SharedLinkOtpWritableAllowlist" + } + ], + "title": "Shared link OTP settings (Write)" + }, + "SharedLinkOtpWritableAllowlist": { + "description": "Anonymous recipients can request a one-time-passcode only when they\nenter an email that matches an entry on the `allowlist`.", + "type": "object", + "properties": { + "mode": { + "description": "Set to `allowlist` to restrict OTP requests to emails matching an\nentry on the `allowlist`.", + "type": "string", + "example": "allowlist", + "enum": [ + "allowlist" + ] + }, + "allowlist": { + "description": "The list of email and domain entries that are permitted to access the\nshared link when `mode` is `allowlist`. Anonymous users whose\nemail matches an entry can request and verify a one-time-passcode.\n\nProviding this field replaces the entire existing allowlist; passing\nan empty array clears all entries. Required when `mode` is `allowlist`.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SharedLinkOtpAllowlistEntryWritable" + }, + "example": [ + { + "type": "email", + "value": "user@example.com" + }, + { + "type": "domain", + "value": "example.com" + } + ], + "maxItems": 1000 + } + }, + "required": [ + "mode", + "allowlist" + ], + "title": "OTP allowlist" + }, + "SharedLinkOtpWritableNone": { + "description": "One-time-passcode (OTP) enforcement is turned off. The shared link is\naccessible without any one-time-passcode verification.", + "type": "object", + "properties": { + "mode": { + "description": "Set to `none` to disable OTP enforcement for the shared link.", + "type": "string", + "example": "none", + "enum": [ + "none" + ] + } + }, + "required": [ + "mode" + ], + "title": "OTP turned off" + }, + "SharedLinkOtpWritableOpen": { + "description": "Any anonymous recipient can request a one-time-passcode to any email\naddress and access the shared link after verifying it. Collaborators\nand registered Box users access the link without being prompted.", + "type": "object", + "properties": { + "mode": { + "description": "Set to `open` to allow any anonymous recipient to request a\none-time-passcode to any email address.", + "type": "string", + "example": "open", + "enum": [ + "open" + ] + } + }, + "required": [ + "mode" + ], + "title": "OTP open" + }, "ShieldInformationBarrier": { "description": "A standard representation of a\nshield information barrier object.", "type": "object", @@ -41031,7 +41418,7 @@ "example": 1000 }, "entries": { - "description": "An list of entries for the card. This represents the individual entries of\nthe transcription.", + "description": "A list of entries for the card. This represents the individual entries of\nthe transcription.", "type": "array", "items": { "type": "object", @@ -42678,7 +43065,7 @@ "example": "2012-12-12T10:53:43-08:00" }, "part_size": { - "description": "The size in bytes that must be used for all parts of of the\nupload.\n\nOnly the last part is allowed to be of a smaller size.", + "description": "The size in bytes that must be used for all parts of the\nupload.\n\nOnly the last part is allowed to be of a smaller size.", "type": "integer", "format": "int64", "example": 1024 @@ -42690,7 +43077,7 @@ "example": 1000 }, "num_parts_processed": { - "description": "The number of parts that have been uploaded and processed\nby the server. This starts at `0`.\n\nWhen committing a file files, inspecting this property can\nprovide insight if all parts have been uploaded correctly.", + "description": "The number of parts that have been uploaded and processed\nby the server. This starts at `0`.\n\nWhen committing a file, inspecting this property can\nprovide insight if all parts have been uploaded correctly.", "type": "integer", "format": "int32", "example": 455 @@ -43670,7 +44057,8 @@ "effective_permission", "is_password_enabled", "download_count", - "preview_count" + "preview_count", + "one_time_passcode" ], "properties": { "url": { @@ -43788,6 +44176,57 @@ "type": "integer", "example": 3, "nullable": false + }, + "one_time_passcode": { + "allOf": [ + { + "title": "Shared link OTP settings", + "description": "One-time-passcode (OTP) settings for a shared link. When OTP enforcement\nis enabled, anonymous users must verify their identity via a\none-time-passcode emailed to them before the shared link will grant\naccess.\n\nOTP can only be used with shared links that have an `access` level of\n`open`. Password protection and OTP cannot be enabled at the same time.", + "type": "object", + "required": [ + "mode" + ], + "properties": { + "mode": { + "description": "The current OTP enforcement mode for the shared link.\n\n* `none` - OTP enforcement is turned off. The shared link is accessible\n without any one-time-passcode verification.\n* `open` - Any anonymous recipient can request a one-time-passcode to\n any email address and access the shared link after verifying it.\n Collaborators and registered Box users access the link without\n being prompted.\n* `allowlist` - Anonymous recipients can request a one-time-passcode\n only when they enter an email that matches an entry on the\n `allowlist`.", + "type": "string", + "example": "allowlist" + }, + "allowlist": { + "description": "The list of email and domain entries that are permitted to access the\nshared link when `mode` is `allowlist`. Anonymous users whose\nemail matches an entry can request and verify a one-time-passcode.\n\nBecause the entries carry recipient email addresses and the identity\nof the user who added them, this field is only returned to users\nwith owner, co-owner, or editor access on the item. For viewer\ncollaborators and below the field is omitted.\n\nAn allowlist contains at most 1000 entries, matching the limit\nenforced when setting the allowlist on a shared link.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SharedLinkOtpAllowlistEntry" + }, + "example": [ + { + "type": "email", + "value": "alice@example.com", + "created_at": "2026-05-19T12:00:00Z", + "created_by": { + "id": "11446498", + "type": "user" + } + }, + { + "type": "domain", + "value": "example.com", + "created_at": "2026-05-19T12:00:00Z", + "created_by": { + "id": "11446498", + "type": "user" + } + } + ], + "maxItems": 1000 + } + } + }, + { + "description": "The one-time-passcode (OTP) settings for this shared link.\n\nThis field is always present. For links where OTP does not\napply (for example, shared links whose `access` is not `open`),\nthe object is returned with `mode` set to `none`." + } + ], + "nullable": false } } }, diff --git a/openapi/openapi-v2025.0.json b/openapi/openapi-v2025.0.json index 7ce68279..6eee2667 100644 --- a/openapi/openapi-v2025.0.json +++ b/openapi/openapi-v2025.0.json @@ -14,7 +14,7 @@ "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "2025.0", - "x-box-commit-hash": "56657ab895" + "x-box-commit-hash": "53bdced3cd" }, "servers": [ { diff --git a/openapi/openapi-v2026.0.json b/openapi/openapi-v2026.0.json index 8cc85c2e..963052a0 100644 --- a/openapi/openapi-v2026.0.json +++ b/openapi/openapi-v2026.0.json @@ -14,7 +14,7 @@ "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "2026.0", - "x-box-commit-hash": "56657ab895" + "x-box-commit-hash": "53bdced3cd" }, "servers": [ { @@ -283,7 +283,371 @@ }, "x-box-tag": "notes", "tags": [ - "Convert to Box note" + "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" ] } }, @@ -539,102 +903,865 @@ "workflow_action" ] }, - "action_type": { - "description": "The type that defines the behavior of this 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": "run_workflow", + "example": "document_split", "enum": [ - "run_workflow" + "document_split" ] }, - "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.", + "id": { + "description": "The unique identifier of the created Document Split job.", "type": "string", - "format": "date-time", - "example": "2026-04-01T10:00:00.000Z" + "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" + } }, - "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" + "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 }, - "created_by": { - "allOf": [ + "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": [ { - "$ref": "#/components/schemas/User--Mini" + "type": "single_page", + "page": 4 }, { - "description": "The user that created the action." + "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 }, - "updated_by": { - "allOf": [ + "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": [ { - "$ref": "#/components/schemas/User--Mini" + "type": "single_page", + "page": 4 }, { - "description": "The user that last updated the action." + "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" ] }, - "workflow": { - "$ref": "#/components/schemas/AutomateWorkflowReference" + "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": [ - "id", "type", - "action_type", - "workflow" + "start", + "end" ], - "title": "Automate Workflow Action" + "title": "Document Split page selection page range", + "x-box-tag": "document_split" }, - "AutomateWorkflowReference": { - "description": "A reference to an Automate workflow.", + "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": { - "id": { - "description": "The identifier for the Automate workflow instance.", - "type": "string", - "example": "545" - }, "type": { - "description": "The object type.", + "description": "Discriminator. Must be `single_page` for this variant.", "type": "string", - "example": "workflow", + "example": "single_page", "enum": [ - "workflow" + "single_page" ] }, - "name": { - "description": "The display name for the Automate workflow.", - "type": "string", - "example": "Contract approval workflow" + "page": { + "description": "A single page number to include.", + "type": "integer", + "format": "int32", + "example": 4, + "minimum": 1 } }, + "additionalProperties": false, "required": [ - "id", - "type" + "type", + "page" ], - "title": "Automate Workflow Reference" + "title": "Document Split page selection single page", + "x-box-tag": "document_split" }, - "AutomateWorkflows": { - "description": "A list of Automate workflow actions.", + "DocumentSplits": { + "description": "A paginated list of Document Split jobs.", + "type": "object", "allOf": [ { "properties": { "entries": { - "description": "Workflow actions available for manual start.", + "description": "A list of Document Split jobs.", "type": "array", "items": { - "$ref": "#/components/schemas/AutomateWorkflowAction" + "$ref": "#/components/schemas/DocumentSplit" } } } @@ -658,111 +1785,60 @@ } } ], - "title": "Automate Workflow Actions", - "x-box-resource-id": "automate_workflows_v2026.0" + "title": "Document Splits", + "x-box-resource-id": "document_splits_v2026.0", + "x-box-tag": "document_split" }, - "AutomateWorkflowStartRequest": { - "description": "Request body to start an Automate workflow.", + "EnterpriseReference": { + "description": "A reference to an enterprise, used when\nnested within another resource.", "type": "object", "properties": { - "workflow_action_id": { - "description": "The callable action ID used to trigger the selected workflow.", + "id": { + "description": "The unique identifier for this enterprise.", "type": "string", - "example": "981" + "example": "1910967" }, - "file_ids": { - "description": "The files to process with the selected workflow.", - "type": "array", - "items": { - "type": "string", - "example": "123" - }, - "example": [ - "123" + "type": { + "description": "The value will always be `enterprise`.", + "type": "string", + "example": "enterprise", + "enum": [ + "enterprise" ], - "minItems": 1 + "nullable": false } }, "required": [ - "workflow_action_id", - "file_ids" + "type", + "id" ], - "title": "Automate Workflow Start Request" + "title": "Enterprise reference" }, - "ClientError": { - "description": "A generic error.", + "FileReference": { + "description": "File reference.", "type": "object", "properties": { "type": { - "description": "The value will always be `error`.", + "description": "The value will always be `file`.", "type": "string", - "example": "error", + "example": "file", "enum": [ - "error" + "file" ], "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.", + "id": { + "description": "ID of the file.", "type": "string", - "example": "abcdef123456", + "example": "42037322", "nullable": false } }, - "title": "Client error", - "x-box-resource-id": "client_error_v2026.0" + "required": [ + "type", + "id" + ], + "title": "File reference" }, "FolderReference": { "description": "Folder reference.", @@ -1518,10 +2594,15 @@ "x-box-tag": "automate_workflows" }, { - "name": "Convert to Box note", + "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.", diff --git a/openapi/openapi.json b/openapi/openapi.json index 580bd2c4..0e76798a 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -14,7 +14,7 @@ "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "2024.0", - "x-box-commit-hash": "56657ab895" + "x-box-commit-hash": "53bdced3cd" }, "servers": [ { @@ -680,6 +680,16 @@ "example": true } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } }, @@ -5451,6 +5461,16 @@ "example": true } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } }, @@ -11736,6 +11756,9 @@ "can_preview": true, "can_download": true, "can_edit": true + }, + "one_time_passcode": { + "mode": "none" } } } @@ -11875,6 +11898,16 @@ "example": true } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } } @@ -11913,6 +11946,9 @@ "can_preview": true, "can_download": true, "can_edit": true + }, + "one_time_passcode": { + "mode": "none" } } } @@ -12082,6 +12118,16 @@ "example": true } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } } @@ -12120,6 +12166,9 @@ "can_preview": true, "can_download": true, "can_edit": true + }, + "one_time_passcode": { + "mode": "none" } } } @@ -12471,6 +12520,9 @@ "can_preview": true, "can_download": true, "can_edit": false + }, + "one_time_passcode": { + "mode": "none" } } } @@ -12611,6 +12663,16 @@ "example": false } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } } @@ -12649,6 +12711,9 @@ "can_preview": true, "can_download": true, "can_edit": false + }, + "one_time_passcode": { + "mode": "none" } } } @@ -12818,6 +12883,16 @@ "example": false } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } } @@ -12856,6 +12931,9 @@ "can_preview": true, "can_download": true, "can_edit": false + }, + "one_time_passcode": { + "mode": "none" } } } @@ -13421,6 +13499,16 @@ "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } } @@ -13745,6 +13833,9 @@ "can_preview": true, "can_download": true, "can_edit": false + }, + "one_time_passcode": { + "mode": "none" } } } @@ -13884,6 +13975,16 @@ "example": false } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } } @@ -13922,6 +14023,9 @@ "can_preview": true, "can_download": true, "can_edit": false + }, + "one_time_passcode": { + "mode": "none" } } } @@ -14091,6 +14195,16 @@ "example": true } } + }, + "one_time_passcode": { + "allOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritable" + }, + { + "description": "One-time-passcode (OTP) settings for the shared link." + } + ] } } } @@ -14129,6 +14243,9 @@ "can_preview": true, "can_download": true, "can_edit": false + }, + "one_time_passcode": { + "mode": "none" } } } @@ -15172,7 +15289,7 @@ "delete": { "operationId": "delete_users_id", "summary": "Delete user", - "description": "Deletes a user. By default, this operation fails if the user\nstill owns any content. \nTo proceed, move their owned content first, or use the `force` parameter to delete\nthe user and their files.", + "description": "Deletes a user. By default, this operation fails if the user\nstill owns any content. \nTo proceed, move their owned content first, or use the `force` parameter to delete\nthe user and their files.\n\nIf the enterprise has a retention policy, including a retired one, or a\nlegal hold that is not fully released, you can't delete a user who owns\ncontent, even with `force`. Transfer the user's content first by using the\n[Transfer owned folders](https://developer.box.com/reference/put-users-id-folders-0)\nendpoint.", "parameters": [ { "name": "user_id", @@ -15196,7 +15313,7 @@ { "name": "force", "in": "query", - "description": "Specifies whether to delete the user even if they still own files.", + "description": "Specifies whether to delete the user even if they still own files.\n\nIf the user owns content and the enterprise has a retention policy,\nincluding a retired one, or a legal hold that is not fully released,\nsetting `force` to `true` doesn't delete the user. The request returns\na `403` error, and you must transfer the user's content before deleting\nthe user.", "schema": { "type": "boolean" }, @@ -15207,6 +15324,16 @@ "204": { "description": "Removes the user and returns an empty response." }, + "403": { + "description": "Returns an error if the user can't be deleted.\n\n* `forbidden` with the message\n `User cannot be deleted due to retention policies. Please transfer user content first`\n when the user owns content and the enterprise has a retention policy,\n including a retired one, or a legal hold that is not fully released. This applies\n even if none of the policies apply to the user's content, and even\n when `force` is set to `true`. Transfer the user's content by using the\n [Transfer owned folders](https://developer.box.com/reference/put-users-id-folders-0)\n endpoint, then try again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientError" + } + } + } + }, "default": { "description": "An unexpected client error.", "content": { @@ -31336,7 +31463,8 @@ "effective_permission", "is_password_enabled", "download_count", - "preview_count" + "preview_count", + "one_time_passcode" ], "properties": { "url": { @@ -31454,6 +31582,57 @@ "type": "integer", "example": 3, "nullable": false + }, + "one_time_passcode": { + "allOf": [ + { + "title": "Shared link OTP settings", + "description": "One-time-passcode (OTP) settings for a shared link. When OTP enforcement\nis enabled, anonymous users must verify their identity via a\none-time-passcode emailed to them before the shared link will grant\naccess.\n\nOTP can only be used with shared links that have an `access` level of\n`open`. Password protection and OTP cannot be enabled at the same time.", + "type": "object", + "required": [ + "mode" + ], + "properties": { + "mode": { + "description": "The current OTP enforcement mode for the shared link.\n\n* `none` - OTP enforcement is turned off. The shared link is accessible\n without any one-time-passcode verification.\n* `open` - Any anonymous recipient can request a one-time-passcode to\n any email address and access the shared link after verifying it.\n Collaborators and registered Box users access the link without\n being prompted.\n* `allowlist` - Anonymous recipients can request a one-time-passcode\n only when they enter an email that matches an entry on the\n `allowlist`.", + "type": "string", + "example": "allowlist" + }, + "allowlist": { + "description": "The list of email and domain entries that are permitted to access the\nshared link when `mode` is `allowlist`. Anonymous users whose\nemail matches an entry can request and verify a one-time-passcode.\n\nBecause the entries carry recipient email addresses and the identity\nof the user who added them, this field is only returned to users\nwith owner, co-owner, or editor access on the item. For viewer\ncollaborators and below the field is omitted.\n\nAn allowlist contains at most 1000 entries, matching the limit\nenforced when setting the allowlist on a shared link.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SharedLinkOtpAllowlistEntry" + }, + "example": [ + { + "type": "email", + "value": "alice@example.com", + "created_at": "2026-05-19T12:00:00Z", + "created_by": { + "id": "11446498", + "type": "user" + } + }, + { + "type": "domain", + "value": "example.com", + "created_at": "2026-05-19T12:00:00Z", + "created_by": { + "id": "11446498", + "type": "user" + } + } + ], + "maxItems": 1000 + } + } + }, + { + "description": "The one-time-passcode (OTP) settings for this shared link.\n\nThis field is always present. For links where OTP does not\napply (for example, shared links whose `access` is not `open`),\nthe object is returned with `mode` set to `none`." + } + ], + "nullable": false } } }, @@ -33208,7 +33387,8 @@ "effective_permission", "is_password_enabled", "download_count", - "preview_count" + "preview_count", + "one_time_passcode" ], "properties": { "url": { @@ -33326,6 +33506,57 @@ "type": "integer", "example": 3, "nullable": false + }, + "one_time_passcode": { + "allOf": [ + { + "title": "Shared link OTP settings", + "description": "One-time-passcode (OTP) settings for a shared link. When OTP enforcement\nis enabled, anonymous users must verify their identity via a\none-time-passcode emailed to them before the shared link will grant\naccess.\n\nOTP can only be used with shared links that have an `access` level of\n`open`. Password protection and OTP cannot be enabled at the same time.", + "type": "object", + "required": [ + "mode" + ], + "properties": { + "mode": { + "description": "The current OTP enforcement mode for the shared link.\n\n* `none` - OTP enforcement is turned off. The shared link is accessible\n without any one-time-passcode verification.\n* `open` - Any anonymous recipient can request a one-time-passcode to\n any email address and access the shared link after verifying it.\n Collaborators and registered Box users access the link without\n being prompted.\n* `allowlist` - Anonymous recipients can request a one-time-passcode\n only when they enter an email that matches an entry on the\n `allowlist`.", + "type": "string", + "example": "allowlist" + }, + "allowlist": { + "description": "The list of email and domain entries that are permitted to access the\nshared link when `mode` is `allowlist`. Anonymous users whose\nemail matches an entry can request and verify a one-time-passcode.\n\nBecause the entries carry recipient email addresses and the identity\nof the user who added them, this field is only returned to users\nwith owner, co-owner, or editor access on the item. For viewer\ncollaborators and below the field is omitted.\n\nAn allowlist contains at most 1000 entries, matching the limit\nenforced when setting the allowlist on a shared link.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SharedLinkOtpAllowlistEntry" + }, + "example": [ + { + "type": "email", + "value": "alice@example.com", + "created_at": "2026-05-19T12:00:00Z", + "created_by": { + "id": "11446498", + "type": "user" + } + }, + { + "type": "domain", + "value": "example.com", + "created_at": "2026-05-19T12:00:00Z", + "created_by": { + "id": "11446498", + "type": "user" + } + } + ], + "maxItems": 1000 + } + } + }, + { + "description": "The one-time-passcode (OTP) settings for this shared link.\n\nThis field is always present. For links where OTP does not\napply (for example, shared links whose `access` is not `open`),\nthe object is returned with `mode` set to `none`." + } + ], + "nullable": false } } }, @@ -35114,7 +35345,7 @@ ] }, "entries": { - "description": "An list of entries in the metadata card.", + "description": "A list of entries in the metadata card.", "type": "array", "items": { "type": "object", @@ -37671,6 +37902,162 @@ "x-box-resource-id": "session_termination", "x-box-tag": "session_termination" }, + "SharedLinkOtpAllowlistEntry": { + "description": "An entry on the OTP allowlist for a shared link. The entry can match\neither a specific email address or every email address that belongs to\na domain.", + "type": "object", + "properties": { + "type": { + "description": "The kind of allowlist entry.\n\n* `email` - The entry matches a single email address.\n* `domain` - The entry matches every email address under the\n given domain.", + "type": "string", + "example": "email", + "enum": [ + "email", + "domain" + ] + }, + "value": { + "description": "The value of the allowlist entry.\n\n* For `email` entries, the full email address (must contain `@`).\n* For `domain` entries, the bare domain (e.g. `example.com`).", + "type": "string", + "example": "alice@example.com" + }, + "created_at": { + "description": "The date and time when the allowlist entry was added.", + "type": "string", + "format": "date-time", + "example": "2026-05-19T12:00:00Z" + }, + "created_by": { + "allOf": [ + { + "$ref": "#/components/schemas/User--Base" + }, + { + "description": "User who added this entry." + } + ] + } + }, + "required": [ + "type", + "value", + "created_at", + "created_by" + ], + "title": "Shared link OTP allowlist entry" + }, + "SharedLinkOtpAllowlistEntryWritable": { + "description": "An entry used to write the OTP allowlist for a shared link. The entry can\nmatch either a specific email address or every email address that\nbelongs to a domain.", + "type": "object", + "properties": { + "type": { + "description": "The kind of allowlist entry.\n\n* `email` - The entry matches a single email address.\n* `domain` - The entry matches every email address under the\n given domain.", + "type": "string", + "example": "email", + "enum": [ + "email", + "domain" + ] + }, + "value": { + "description": "The value of the allowlist entry.\n\n* For `email` entries, the full email address (must contain `@`).\n* For `domain` entries, the bare domain (e.g. `example.com`).", + "type": "string", + "example": "alice@example.com" + } + }, + "required": [ + "type", + "value" + ], + "title": "Shared link OTP allowlist entry (Write)" + }, + "SharedLinkOtpWritable": { + "description": "One-time-passcode (OTP) settings for a shared link. When OTP enforcement\nis enabled, anonymous users must verify their identity via a\none-time-passcode emailed to them before the shared link will grant\naccess.\n\nOTP can only be used with shared links that have an `access` level of\n`open`. Password protection and OTP cannot be enabled at the same time.", + "oneOf": [ + { + "$ref": "#/components/schemas/SharedLinkOtpWritableNone" + }, + { + "$ref": "#/components/schemas/SharedLinkOtpWritableOpen" + }, + { + "$ref": "#/components/schemas/SharedLinkOtpWritableAllowlist" + } + ], + "title": "Shared link OTP settings (Write)" + }, + "SharedLinkOtpWritableAllowlist": { + "description": "Anonymous recipients can request a one-time-passcode only when they\nenter an email that matches an entry on the `allowlist`.", + "type": "object", + "properties": { + "mode": { + "description": "Set to `allowlist` to restrict OTP requests to emails matching an\nentry on the `allowlist`.", + "type": "string", + "example": "allowlist", + "enum": [ + "allowlist" + ] + }, + "allowlist": { + "description": "The list of email and domain entries that are permitted to access the\nshared link when `mode` is `allowlist`. Anonymous users whose\nemail matches an entry can request and verify a one-time-passcode.\n\nProviding this field replaces the entire existing allowlist; passing\nan empty array clears all entries. Required when `mode` is `allowlist`.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SharedLinkOtpAllowlistEntryWritable" + }, + "example": [ + { + "type": "email", + "value": "user@example.com" + }, + { + "type": "domain", + "value": "example.com" + } + ], + "maxItems": 1000 + } + }, + "required": [ + "mode", + "allowlist" + ], + "title": "OTP allowlist" + }, + "SharedLinkOtpWritableNone": { + "description": "One-time-passcode (OTP) enforcement is turned off. The shared link is\naccessible without any one-time-passcode verification.", + "type": "object", + "properties": { + "mode": { + "description": "Set to `none` to disable OTP enforcement for the shared link.", + "type": "string", + "example": "none", + "enum": [ + "none" + ] + } + }, + "required": [ + "mode" + ], + "title": "OTP turned off" + }, + "SharedLinkOtpWritableOpen": { + "description": "Any anonymous recipient can request a one-time-passcode to any email\naddress and access the shared link after verifying it. Collaborators\nand registered Box users access the link without being prompted.", + "type": "object", + "properties": { + "mode": { + "description": "Set to `open` to allow any anonymous recipient to request a\none-time-passcode to any email address.", + "type": "string", + "example": "open", + "enum": [ + "open" + ] + } + }, + "required": [ + "mode" + ], + "title": "OTP open" + }, "ShieldInformationBarrier": { "description": "A standard representation of a\nshield information barrier object.", "type": "object", @@ -41031,7 +41418,7 @@ "example": 1000 }, "entries": { - "description": "An list of entries for the card. This represents the individual entries of\nthe transcription.", + "description": "A list of entries for the card. This represents the individual entries of\nthe transcription.", "type": "array", "items": { "type": "object", @@ -42678,7 +43065,7 @@ "example": "2012-12-12T10:53:43-08:00" }, "part_size": { - "description": "The size in bytes that must be used for all parts of of the\nupload.\n\nOnly the last part is allowed to be of a smaller size.", + "description": "The size in bytes that must be used for all parts of the\nupload.\n\nOnly the last part is allowed to be of a smaller size.", "type": "integer", "format": "int64", "example": 1024 @@ -42690,7 +43077,7 @@ "example": 1000 }, "num_parts_processed": { - "description": "The number of parts that have been uploaded and processed\nby the server. This starts at `0`.\n\nWhen committing a file files, inspecting this property can\nprovide insight if all parts have been uploaded correctly.", + "description": "The number of parts that have been uploaded and processed\nby the server. This starts at `0`.\n\nWhen committing a file, inspecting this property can\nprovide insight if all parts have been uploaded correctly.", "type": "integer", "format": "int32", "example": 455 @@ -43670,7 +44057,8 @@ "effective_permission", "is_password_enabled", "download_count", - "preview_count" + "preview_count", + "one_time_passcode" ], "properties": { "url": { @@ -43788,6 +44176,57 @@ "type": "integer", "example": 3, "nullable": false + }, + "one_time_passcode": { + "allOf": [ + { + "title": "Shared link OTP settings", + "description": "One-time-passcode (OTP) settings for a shared link. When OTP enforcement\nis enabled, anonymous users must verify their identity via a\none-time-passcode emailed to them before the shared link will grant\naccess.\n\nOTP can only be used with shared links that have an `access` level of\n`open`. Password protection and OTP cannot be enabled at the same time.", + "type": "object", + "required": [ + "mode" + ], + "properties": { + "mode": { + "description": "The current OTP enforcement mode for the shared link.\n\n* `none` - OTP enforcement is turned off. The shared link is accessible\n without any one-time-passcode verification.\n* `open` - Any anonymous recipient can request a one-time-passcode to\n any email address and access the shared link after verifying it.\n Collaborators and registered Box users access the link without\n being prompted.\n* `allowlist` - Anonymous recipients can request a one-time-passcode\n only when they enter an email that matches an entry on the\n `allowlist`.", + "type": "string", + "example": "allowlist" + }, + "allowlist": { + "description": "The list of email and domain entries that are permitted to access the\nshared link when `mode` is `allowlist`. Anonymous users whose\nemail matches an entry can request and verify a one-time-passcode.\n\nBecause the entries carry recipient email addresses and the identity\nof the user who added them, this field is only returned to users\nwith owner, co-owner, or editor access on the item. For viewer\ncollaborators and below the field is omitted.\n\nAn allowlist contains at most 1000 entries, matching the limit\nenforced when setting the allowlist on a shared link.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SharedLinkOtpAllowlistEntry" + }, + "example": [ + { + "type": "email", + "value": "alice@example.com", + "created_at": "2026-05-19T12:00:00Z", + "created_by": { + "id": "11446498", + "type": "user" + } + }, + { + "type": "domain", + "value": "example.com", + "created_at": "2026-05-19T12:00:00Z", + "created_by": { + "id": "11446498", + "type": "user" + } + } + ], + "maxItems": 1000 + } + } + }, + { + "description": "The one-time-passcode (OTP) settings for this shared link.\n\nThis field is always present. For links where OTP does not\napply (for example, shared links whose `access` is not `open`),\nthe object is returned with `mode` set to `none`." + } + ], + "nullable": false } } },