# Bulk writes

[Open in the interactive reference](https://docs.api.lensing.ai/?op=guide%3Abulk)

Some resources have bulk endpoints, which create or delete many records in one call. Most are `POST <resource>/bulk` and `POST <resource>/bulk-delete`; a few other endpoints restore or update several records at once. Check a resource's endpoints before you plan a batch.

**A bulk call is one transaction.** Either every entry is written or none is, and one invalid entry fails the whole call. To write entries independently, call the single-record endpoint once per entry. A bulk call accepts an `Idempotency-Key` like any other write.

On most bulk endpoints, an error about one entry names it by its `index`, its position in the input array, in the diagnostic's `details`. The rest of `details` varies by endpoint; its error list shows the shape.

Do not send an empty batch. Some bulk endpoints refuse one, for example with `NOTHING_TO_CREATE`; others accept it and write nothing.

A successful call usually returns one result per entry, in input order, including each new id for a bulk create. What exactly comes back varies by endpoint, and its response shows it.

## Examples

**A bulk create**

```
POST /inventory/items/bulk
{ "items": [ … ] }

HTTP/1.1 200 OK

{ "data": { "created": [
    { "id": "9f2c…", "itemCode": "WIDGET-01" },
    { "id": "3b7d…", "itemCode": "WIDGET-02" }
] } }
```

**One bad entry**

```json
{
  "error": {
    "code": "DUPLICATE_CODE",
    "message": "…",
    "diagnostics": [
      {
        "code": "DUPLICATE_CODE",
        "severity": "error",
        "message": "…",
        "details": {
          "itemCode": "WIDGET-01",
          "index": 3
        }
      }
    ]
  }
}
```