Add, update and delete many dataset items
Apply a batch of creates, updates and deletes to a dataset’s items in a single committed version.
This is not replace-all. Only the items named in items and delete_ids are touched; every other item of the dataset is left exactly as it was. Omitting an id does not delete it.
Each entry of items is a whole-item replace, in exactly the shape POST /evals/datasets/{dataset_id}/items accepts. An absent field is an empty field, not “keep whatever is there”. Whole-item semantics is what makes one payload mean the same thing whether it creates or updates, and it is how a bulk request clears a field.
An entry whose id is currently live is an update; an entry with no id, or with an id that is unknown or whose last revision was a delete, is a create (a re-submitted deleted id begins a new lifetime). An entry whose content matches the item’s current content (absent, null and empty treated alike, as on POST) writes nothing at all — its id comes back under unchanged_ids. A batch in which nothing changed creates no new version and still answers 200.
The whole batch lands under exactly one version, however many items it touches, so a read at any version sees either all of it or none of it.
items and delete_ids are capped together: their combined length may not exceed the bulk limit (by default the dataset item cap, 10,000); a request over it is a 400 whose message states the exact limit. Creates are also held under the dataset’s overall item cap, measured on the batch’s net effect — a batch that deletes fifty items and creates fifty more does not grow the dataset.
base_version is required: the version the caller read, typically data.dataset_version.version from the item listing. If any id named in items or delete_ids has a revision (an edit, a delete or a re-create) committed above that version, the whole request is refused with a 409 whose reason is DatasetItemStaleBaseVersion and nothing is written, even when the batch would otherwise change nothing. The check is per item: an older base_version is still accepted for items that have not changed since it. A retry of a request whose response was lost therefore gets a 409; re-read the listing to see that the change was applied.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Dataset UUID
Body
One bulk add/update/delete. Both halves are optional, but at least one of them must be non-empty, and their combined length is capped (by default at the dataset item cap, 10,000). An item id may appear only once across both lists.
Optimistic-concurrency check: the dataset version the caller read. The whole request is refused with 409 if any id it names has a revision committed above that version.
Items to add or update. Each entry is the whole item, in exactly the shape the POST accepts — an absent field is an empty field, not "keep the current value". An entry with no id, or with an id that is not currently live, creates a new item.
Ids to delete. Every id must name a live item of this dataset; if any does not, the whole batch is refused with 404.
Response
The batch was applied. The four id lists partition the ids the request named.
Response object for standard API responses.
API version.
2.0, 3.0 Type of response, indicating a normal response.
NORMAL The outcome of a bulk request, per id rather than as a count: the four lists partition the ids the request named. An id in unchanged_ids was submitted with content identical to what was already stored, so no revision was written for it.