---
title: "Create or update Dataset Cases under client-supplied identity"
method: PUT
path: "/api/{org_id}/datasets/{dataset_id}/items"
tags: ["Datasets"]
---

# Create or update Dataset Cases under client-supplied identity

`PUT /api/{org_id}/datasets/{dataset_id}/items`

## Request

- Base URL: `https://api.openobserve.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.openobserve.ai/api/{org_id}/datasets/{dataset_id}/items`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/openobserve/apis/openobserve-api-http/docs/api/:org_id/datasets/:dataset_id/items/put.ts> (a function with typed inputs; its response is checked against the schema)

Identity comes from `logicalId` alone and is never inferred from content. An item that names an existing Case must carry the `ifRowId` it read; a superseded revision returns 409 and writes nothing. A deleted Case returns 409 unless the item sets `restore`. The whole batch and its idempotency record commit together.

## Path parameters

- `org_id` string, required
- `dataset_id` string, required

## Request body

- object
  - `idempotencyKey` string, nullable: Client-generated key, scoped to this organization and Dataset. Repeating it with identical content replays the first response.
  - `items` UpsertDatasetItemBody[], required
    - `expectedOutput` unknown
    - `ifRowId` string, nullable: The `rowId` the client read. Required when `logicalId` names an existing Case.
    - `input` unknown, required
    - `logicalId` string, nullable: Stable Dataset Case identity, at most 27 characters. Omit to append a new Case with a server-generated identity.
    - `metadata` unknown
    - `restore` boolean: Bring a soft-deleted Case back instead of conflicting on it.
    - `tags` string[]

## Response `200`

- object
  - `datasetVersion` integer, required
  - `items` UpsertedDatasetItemBody[], required
    - `globalVersion` integer, required
    - `logicalId` string, required
    - `outcome` 'created' | 'updated' | 'restored' | 'unchanged', required
    - `rowId` string, required
  - `replayed` boolean, required: True when the response was replayed from a stored idempotency record.

## Other responses

- `400`: Invalid upsert request
- `404`: Dataset not found
- `409`: Stale revision, deleted Case, or idempotency conflict

---

[API](https://skmtc.dev/openobserve/apis/openobserve-api-http.md) - [All operations](https://skmtc.dev/openobserve/apis/openobserve-api-http/llms.txt) - [OpenAPI document](https://skmtc.dev/openobserve/apis/openobserve-api-http/revisions/0529b8a10252?raw)