Batch Operations
POST/batch
Perform multiple operations in a single request.
This endpoint allows you to perform multiple API operations in a single request.
The requests can be to different resources (endpoints or URLs) or to
the same resource. The operations can be of different types, namely
GET, POST, PUT, and DELETE. The batch request itself should
always be a POST request.
In general, this is mostly intended for creating, modifying, or deleting
multiple resources at once, as opposed to reading multiple collections or
objects (using GET). It's important to note that when modifying objects
through a batch request, you still need to include the If-Match header
with the current ETag value in each modification request as
documented here.
There is no way to automatically fetch the current ETag and apply it to a
modification within the same batch request.
Note: the maximum length of a batch request is 100 requests. If the batch array is longer than 100, the server will return an error.
Note that you cannot make a nested batch request within a batch request.
The batch request itself should be authenticated using the normal authentication methods. The server will ignore any authentication headers within each request. The same user account (identity) will be used for all requests in the batch.
The request body should be a JSON object with the following structure:
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 500
- 503
The batch operation was successful. The response body contains the results of each individual operation.
:::info About response codes
The response code for each operation is included in the response body. The response code for the batch operation itself is always 200, even if individual operations failed. However, the batch operation itself can return a non-200 error code if the batch request is malformed or if the server is unable to process the request for another reason.
:::
Note that the index of each response in the array corresponds to the
index of the request in the original batch request. If
stop_on_error is true, the response array will stop at the first
error encountered.
A 400 Bad Request is returned when the client request was malformed,
invalid, or otherwise could not be processed as-is. Usually, the cause for
the error is included in the error.message field of the response, and the
client should correct the request and try again.
See also Core Concepts#Error Responses.
Not authenticated - you must be signed in to access this resource. Please check the section of the documentation on authentication.
A 403 Forbidden response means that you are not authorized to perform
this action or access this object, or the object does not exist at all.
The client request may have been valid but the client does not have permission to access the requested resource or perform the requested action.
:::tip 403 Forbidden also used when objects don't exist
In most cases, the system will not return a 404 Not Found error response;
it returns 403 Forbidden both when the object doesn't exist at all,
and also when it exists but the client does not have permission to access it.
This is a security measure to prevent unauthorized users from determining
whether an object exists or not.
:::
See also Core Concepts#Error Responses.
Not found - the requested resource could not be found or does not exist. This may also include cases where the resource does exist, but the client does not have permission to access that resource.
:::tip 403 Forbidden also used when objects don't exist
In most cases, the system will not return a 404 Not Found error response;
it returns 403 Forbidden both when the object doesn't exist at all,
and also when it exists but the client does not have permission to access it.
This is a security measure to prevent unauthorized users from determining
whether an object exists or not.
:::
See also Core Concepts#Error Responses.
Internal server error; an unexpected error occurred on the server. This could be due to a temporary condition or might be the result of a bug in the server software. Also, in some cases, an incorrect client input can trigger this error, and can be resolved by correcting the input.
If the error persists, please contact support along along with the following details when possible:
- any error messages received from the server
- the full request and response details (full headers and body)
- a description of the steps that led to the error
- the time range when it occurred.
Service unavailable - the server is currently unable to handle the request, usually due to maintenance activity on the server. Check if the server's web interface is currently available, or try again later.