Bulk patch multiple documents

patch/documents/{rootEntityTypeName}/{rootDocumentId}/bulk

Partially updates multiple documents in a single request. This endpoint reduces the number of round trips required to update multiple documents by allowing the client to send only the changed fields rather than the full document content.

The root document, specified in the path, serves as an organizational anchor for the patches. Conceptually, it represents the page the user is currently viewing. The root document is not required to be related to the documents specified in the request body — any document the user has permission to modify can be patched.

Patches are represented as JSON Patch objects. For more information, see jsonpatch.com.

Only update operations are supported. The following JSON Patch operations are allowed:

add
remove
replace

A document can only be referenced once in the collection of bulk patch operations.

To manually control document lock acquisition and release, use the manuallyManageLocks query parameter.

To include the full updated document in the response, use the Accept-Item header.

Request Samples

Response Samples


1{
2  "name": "items",
3  "count": 2,
4  "version": 2,
5  "items": [
6    {
7      "id": "abc123",
8      "entityType": "incident",
9      "operation": "UPDATE"
10    },
11    {
12      "id": "def456",
13      "entityType": "incident",
14      "error": {
15        "errorCode": 0,
16        "message": "The JSON patch operation \"move\" is not supported. Only the following operations are supported: \"add\", \"replace\", and \"remove\".",
17        "id": "json_patch_operation_not_supported",
18        "version": 2,
19        "httpStatusCode": 400,
20        "details": [
21          "Entity Type: incident",
22          "Entity ID: def456"
23        ]
24      }
25    }
26  ]
27}

Path Parameters

Name	Type	Required	Description
rootEntityTypeName	string	true	The entity type of the root document.
rootDocumentId	string	true	The ID of the root document.

Query Parameters

Name	Type	Required	Description
manuallyManageLocks	boolean	false	Controls whether the client is responsible for acquiring and releasing document locks. By default (`false`), each document patch automatically acquires a lock before updating the document and releases the lock afterward. When set to `true`, the client is responsible for acquiring and releasing document locks. In this mode: The update will fail if the client has not acquired the lock before sending the PATCH request. The client is responsible for releasing the lock regardless of whether the update succeeds or fails. A document lock is always required for a successful update. This requirement cannot be bypassed. Setting `manuallyManageLocks` to `true` is useful when the client wants to hold the lock across a validation failure, preventing another user from acquiring the lock while the current user corrects errors. Default: false

Header Parameters

Name	Type	Required	Description
Accept-Item	string	false	Specifies the media type for items in the response collection. `application/vnd.sas.investigation.data.document.bulk.operation.result` returns the operation result without the updated document, producing a smaller response payload. `application/vnd.sas.investigation.data.document.enriched.bulk.operation.result` returns the operation result with the fully enriched document, including child documents. Masked fields are represented as nine dots. This is useful for avoiding additional GET requests after updates are complete. Allowed values: application/jsonapplication/vnd.sas.investigation.data.document.bulk.operation.resultapplication/vnd.sas.investigation.data.document.bulk.operation.result+jsonapplication/vnd.sas.investigation.data.document.enriched.bulk.operation.resultapplication/vnd.sas.investigation.data.document.enriched.bulk.operation.result+json
Content-Item-Type	string	false	The media type of each item in the request body collection. Allowed values: application/vnd.sas.investigation.data.document.bulk.operation.patchapplication/vnd.sas.investigation.data.document.bulk.operation.patch+json

Request Body

A collection of bulk document patch items. Each item identifies a document by entity type and ID and includes the JSON Patch operations to apply to it.

A collection of bulk document patch items. Each item identifies a document and the JSON Patch operations to apply to it.

Name	Type	Required	Description
name	string	false	The name of the collection.
start	integer<int64>	false	The zero-based index of the first item in the collection.
limit	integer	false	The number of items that were requested for the collection.
count	integer<int64>	false	If populated, indicates the number of items in the collection.
accept	string	false	A space-delimited list of media types from which an `Accept` header can be constructed.
links	array [SAS Link]	false	The links that apply to the collection.
version	integer	false	The version number of the collection representation. This representation is version 2.
items	array [Bulk Document Patch Item]	true	The array that contains the bulk document patch items.

Responses

Status	Meaning	Description
200	OK	The bulk patch operation completed. Each item in the response collection indicates whether the patch operation for the corresponding document succeeded or failed. Result items are in the same order as the input collection.	Schema
400	Bad Request	The request was invalid.	Schema
404	Not Found	No root document exists at the requested path.	Schema
412	Precondition Failed	The `If-Match` version provided for a document does not match the current version of the document. The document may have been modified by another user.	Schema
415	Unsupported Media Type	The requested media type is not supported.	Schema