# POST /api/batch

> Batch - Run Batch Operations

Execute up to 50 operations in one request, in the order they were sent. Operations use the same names and arguments as the MCP tools exposed by /api/mcp (for example clients_list , clients_get , clients_search , invoices_create , tasks_update , taxes_delete , plus the lookup tools such as list_task_statuses and the utilities get_current_datetime and get_server_info ). Names follow the resource_action convention, where action is one of list, get, search, create, update or delete. When the MCP server is enabled you can also call tools/list on it to discover every available operation name and its argument schema. Because the operations run through the same registry as the MCP server, they inherit the same protections: credential and secret columns are never returned, write payloads are whitelisted against the real table columns, privilege columns cannot be mass assigned and administrator or staff accounts cannot be modified. Every operation name is additionally checked against the tool catalogue this token can see before it runs, so a name that is not catalogued is refused instead of being executed. Batch is a REST feature in its own right and does not require the MCP server: it ignores the api_mcp_enabled setting, so it keeps working on a site where MCP is deliberately switched off. It has its own kill switch instead, api_batch_enabled , which is ON unless it is explicitly turned off - set it to 0 in the RISE settings to disable this endpoint (it then answers 403) without disabling the rest of the REST API. The default behaviour is continue-on-error: a failing operation does not abort the batch, it is simply reported as failed and the next one runs. Send stop_on_error as true to abort at the first failure instead; the operations that were never attempted are counted in skipped and do not appear in results . Each result carries its zero based index , the tool that was requested, an ok flag and then either data (on success) or error (on failure). The HTTP status is 200 even when some operations fail - read the per-item ok flags and the failed counter to find out what happened. Batch operations are not transactional: successful writes are not rolled back when a later operation fails.

- **Endpoint:** `POST /api/batch`
- **Group:** Batch
- **Since:** v1.0.0
- **Defined in:** `RestApi/Controllers/BatchController.php`

## Headers

| Field | Type | Description |
| --- | --- | --- |
| `authtoken` | String | Authentication token, generated from admin area |

## Parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `operations` | Object[] | yes | Mandatory Non-empty list of operations to run, maximum 50 |
| `operations.tool` | String | yes | Mandatory Name of the MCP tool to run, for example clients_create. The alias name is also accepted |
| `operations.arguments` | Object | no | Optional Arguments for that tool. Defaults to an empty object. The alias args is also accepted |
| `stop_on_error` | Boolean | no | Optional Abort the batch at the first failing operation instead of continuing Default: `false`. |

## Request example

```bash
curl -X POST "https://yoursite.com/index.php/api/batch" \
  -H "authtoken: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "operations": "...", "operations.tool": "..." }'
```

## Responses

### Success - Success-Response:

```json
HTTP/1.1 200 OK
{
  "status": true,
  "total": 2,
  "completed": 2,
  "failed": 0,
  "skipped": 0,
  "stopped_on_error": false,
  "stopped_at_index": null,
  "results": [
    {
      "index": 0,
      "tool": "clients_create",
      "ok": true,
      "data": {
        "status": true,
        "id": 142,
        "record": {
          "id": "142",
          "company_name": "Acme Corporation",
          "city": "San Francisco",
          "created_date": "2026-02-14 09:21:45"
        }
      }
    },
    {
      "index": 1,
      "tool": "taxes_list",
      "ok": true,
      "data": {
        "count": 2,
        "limit": 2,
        "offset": 0,
        "records": [
          { "id": "1", "title": "VAT (24%)", "percentage": "24.00" },
          { "id": "2", "title": "Tax (10%)", "percentage": "10.00" }
        ]
      }
    }
  ]
}
```

### Success - Partial-Failure-Response:

```json
HTTP/1.1 200 OK
{
  "status": false,
  "total": 3,
  "completed": 2,
  "failed": 1,
  "skipped": 0,
  "stopped_on_error": false,
  "stopped_at_index": null,
  "results": [
    { "index": 0, "tool": "clients_create", "ok": true,  "data": { "status": true, "id": 142 } },
    { "index": 1, "tool": "invoices_get",   "ok": false, "error": "Invoice 999 was not found." },
    { "index": 2, "tool": "tasks_update",   "ok": true,  "data": { "status": true, "id": 88 } }
  ]
}
```

### Success - Stopped-On-Error-Response:

```json
HTTP/1.1 200 OK
{
  "status": false,
  "total": 3,
  "completed": 1,
  "failed": 1,
  "skipped": 1,
  "stopped_on_error": true,
  "stopped_at_index": 1,
  "results": [
    { "index": 0, "tool": "clients_create", "ok": true,  "data": { "status": true, "id": 142 } },
    { "index": 1, "tool": "invoices_get",   "ok": false, "error": "Invoice 999 was not found." }
  ]
}
```

### Error - Batch-Disabled:

```json
HTTP/1.1 403 Forbidden
{
  "status": 403,
  "error": 403,
  "messages": {
    "error": "The batch endpoint is disabled. An administrator can turn it back on by setting \"api_batch_enabled\" to 1 in the RISE settings."
  }
}
```

### Error - Missing-Operations:

```json
HTTP/1.1 400 Bad Request
{
  "status": 400,
  "error": 400,
  "messages": {
    "operations": "Provide a non-empty \"operations\" array, where each entry names an MCP tool and its arguments."
  }
}
```

### Error - Too-Many-Operations:

```json
HTTP/1.1 400 Bad Request
{
  "status": 400,
  "error": 400,
  "messages": {
    "error": "Too many operations: 120 were sent but a batch may carry at most 50. Split the work into smaller batches."
  }
}
```

### Error - Unknown-Operation (reported per item, not as an HTTP error):

```json
HTTP/1.1 200 OK
{
  "status": false,
  "total": 1,
  "completed": 0,
  "failed": 1,
  "skipped": 0,
  "stopped_on_error": false,
  "stopped_at_index": null,
  "results": [
    { "index": 0, "tool": "clients_purge", "ok": false, "error": "Unknown operation \"clients_purge\". Batch only runs operations that exist in the tool catalogue this token can see." }
  ]
}
```

---

Part of the [REST API for RISE CRM](https://risecrm.themesic.com/apiguide/) documentation.
Full page: https://risecrm.themesic.com/apiguide/batch/run-batch/