REST - Batch

Beginning with version 2018.1.1, developers can utilize the new Batch REST endpoint to group together multiple sequential calls into a single network request. For environments which make a number of programmatic alterations to the session configurations, Batch REST can significantly reduce the network load and speed up the initial session creation.

Batch REST works a little differently than the rest of the REST endpoints. In particular, the Batch endpoint does not accept a Session ID URL parameter. This means that the first call in every batch request must be to POST /Sessions, to create a new session. And batch requests cannot operate on preexisting REST sessions - they must always create a new one. However, once you retrieve the session ID from a batch response, you can make normal, non-batch requests to that session.

When supplied as part of a batch call, the individual requests are evaluated sequentially in the order they are supplied.

Note: The GET|PATCH|DELETE /Sessions/{sid} endpoints are not supported by Batch REST.

Batch JSON

The body of a Batch call is formatted as an array of Batch objects, each of which has the following JSON format:

Name Type Writeable Description
Url string required REST endpoint URL (following /rest/)
Note: Case-sensitive. Resource names must begin with a capital letter.
Method constant required Request method, one of: POST, PATCH, GET, DELETE
Payload Payload yes Optional payload for POST and PATCH calls.


    "Url": "Sessions",
    "Method": "POST"
    "Url": "Roles/MyRole",
    "Method": "PATCH",
    "Payload": { ... }

Payload JSON

The format of the Payload property depends on the Url, and mirrors the payload supplied for the non-batch versions of the specified endpoint. For example, when the Url is "Parameters", the payload has the following format (as detailed in the REST - Parameters article):

  "Id":         "MyParameter",
  "DataType":   "String",
  "Value":      "",
  "PromptText": "Input a value",
  "IsHidden":   true

Making Batch Calls

POST /rest/batch

All Batch calls are made using the POST method. There is no session ID parameter; however, calls to the Batch endpoint require the same Headers as all other REST calls. Each request object is supplied in order of evaluation. The response object contains the responses from each request in the same order that they were sent.

Available parameters

Name Type Description
config string Specify which config file to create the session with.

Format: CustomConfigFile

Caution. All config files must use the same Temp path. Otherwise, you may experience errors when loading sessions.

Response JSON

Name Type Description
ReturnCode string Response code indicating whether the call was successful
ResponseContent object If the response code is 200 or 201, this is the content of the response. Otherwise this indicates whether an error occurred and the error type.

ResponseContent JSON

ReturnCode: 204

Name Type Description
StatusCode int Status code
StatusDescription string Status description

ReturnCode: 400-500

Name Type Description
reason string Error message
stacktrace string Stack trace, if available

Using curl

curl http://{webservice}/rest/batch -X POST ^
	-d "[{'Url':'Sessions','Method':'POST'}, ^

Example response

    "ReturnCode": "201",
    "ResponseContent": {
      "AppUrl": "ExagoHome.aspx?...",
      "ApiKey": "...",
      "Id": "...",
      "Page": "ExagoHome",
      "ApiAction": "Default",
      "ExportType": null,
      "ShowTabs": true,
      "ShowErrorDetail": true,
      "ReportSettings": {
        "Id": null,
        "ReportPath": null,
        "SortsResource": null,
        "FilterItems": null,
        "IsError": false,
        "ErrorList": null
    "ReturnCode": "204",
    "ResponseContent": {
      "StatusCode": 204,
      "StatusDescription": null

Hidden Article Information

Article Author
Exago Development
created 2018-05-21 15:31:29 UTC
updated 2018-06-04 19:10:32 UTC

config, web, service, setting, api, file, bulk,
Have more questions? Submit a request