Batch Requests

REGOS API often requires several methods to be executed in sequence, especially when a later request needs a value produced by an earlier one. Batch requests solve this by grouping several API calls into one HTTP request and returning a structured response for every step.

A batch request can contain no more than 50 steps.

How batch requests work

A batch request is sent to .../v1/batch. The request contains a list of steps. Each step has a unique key, a method path, and a payload object with the body that would normally be sent to that method.

The key value must be unique within one batch request.

Steps can be independent, or they can use values from earlier steps. Dependencies are expressed with placeholders in the ${stepKey.property} format. The server resolves these placeholders before executing the dependent step.

For example, if the first step creates a producer, the new ID can be used in a later step:

${ProducerAdd.result.new_id}

If a method returns an array, access items by index:

${ProducerList.result.0.id}

The stop_on_error flag controls execution after a failed step. If it is true, the batch stops at the first unsuccessful step. If it is false, the server continues executing the remaining steps and returns the result for each one.

Steps that already completed before the batch stops are not rolled back.

Each step has its own execution timeout. If a step does not complete in time, the response for that step contains a timeout error. Batch calls cannot call batch again, and high-load methods such as Item/Import are blocked inside batch execution.

Do not call batch from inside batch.

The response contains a responses array. Each item contains the step key, HTTP status, and response body. Successful method calls return the standard API response with ok and result; failed method calls return an ErrorResult body.

The following example creates a producer and then immediately retrieves it by the ID returned from the first step:

{
  "stop_on_error": false,
  "requests": [
    {
      "key": "ProducerAdd",
      "path": "Producer/Add",
      "payload": { "name": "Coca-Cola" }
    },
    {
      "key": "ProducerGet",
      "path": "Producer/Get",
      "payload": { "ids": ["${ProducerAdd.result.new_id}"] }
    }
  ]
}

Example response:

{
  "ok": true,
  "result": [
    {
      "key": "ProducerAdd",
      "status": 200,
      "response": {
        "ok": true,
        "result": {
          "new_id": 4
        }
      }
    },
    {
      "key": "ProducerGet",
      "status": 200,
      "response": {
        "ok": true,
        "result": [
          {
            "id": 4,
            "name": "Coca-Cola",
            "last_update": 1758289402
          }
        ],
        "next_offset": 0,
        "total": 1
      }
    }
  ]
}

Generated Contract

[POST] .../v1/batch

Executes several API requests as a single batch. Use this workflow method when a client needs to execute a small ordered list of independent API calls and receive every step response in one response payload. The request body is required, requests must be a non-empty list with at most 50 steps, every step Key must be unique, path must use Controller/Method or Namespace/Controller/Method format, payload must be provided and stop_on_error stops execution after the first step-level error. The method runs each step in the current request user context, blocks recursive or sensitive paths such as Batch, Sys, Auth, Report/AddRequest, Sync and import/fill operations and returns a BatchResponse containing per-step status and response bodies. Missing body, empty or oversized batch, duplicate keys, invalid step parameters, forbidden paths, reflection/binding errors, step timeouts and invoked-method business errors are returned as HTTP 200 ErrorResult either for the whole batch or inside a step response.

Request Parameters

Name	Type	Required	Description
requests	Array of BatchStep	Required	List of batch steps. Maximum 50 items.
stop_on_error	Boolean	Optional	If true, the batch stops at the first unsuccessful step.

Request Example

{
  "stop_on_error": true,
  "requests": [
    {
      "Key": "get_items",
      "path": "Item/Get",
      "payload": {
        "filters": [
          {
            "Field": "name",
            "Operator": "Like",
            "Value": "milk"
          }
        ],
        "limit": 10,
        "offset": 0
      }
    },
    {
      "Key": "get_roles",
      "path": "Role/Get",
      "payload": {
        "limit": 10,
        "offset": 0
      }
    }
  ]
}

Response Parameters

Name	Type	Description
ok	Boolean	Indicates whether the request completed successfully.
result	BatchResponse	Result object.

Response Example

{
  "ok": true,
  "result": {
    "responses": [
      {
        "key": "get_items",
        "status": 200,
        "response": {
          "ok": true,
          "result": []
        }
      },
      {
        "key": "get_roles",
        "status": 200,
        "response": {
          "ok": true,
          "result": []
        }
      }
    ]
  }
}