Create/update dataset items | Opik Documentation

PUT/v1/private/datasets/itemsCreate/update dataset items

Create/update dataset items based on dataset item id. Each item's 'id' field is the stable identifier and upsert key. Provide it to update an existing item, or omit it to create a new one.

Set 'copy_from_dataset_id' and 'copy_from_version_id' together to read carry-forward rows from the supplied (dataset, version) pair instead of the destination's prior version. When the fields are null, carry-forward rows are read from the destination's prior version.

Request body

application/json

objectDatasetItemBatch_Write

batch_group_idstring · uuid

Optional batch group ID to group multiple batches into a single dataset version. If null, mutates the latest version instead of creating a new one.

copy_from_dataset_idstring · uuid

Optional. Dataset to read carry-forward rows from when materializing the new version. Required together with copy_from_version_id. When null, carry-forward rows are read from the destination dataset's prior version.

copy_from_version_idstring · uuid

Optional. Version within copy_from_dataset_id to read carry-forward rows from. Required together with copy_from_dataset_id.

dataset_idstring · uuid

If null, dataset_name must be provided

dataset_namestring

If null, dataset_id must be provided

pattern (?s)^\s*(\S.*\S|\S)\s*$

itemsarray of objectrequired

maxItems 1000 · minItems 1

Show child attributes

maxItems 1000 · minItems 1

Show array items

dataobjectrequired

descriptionstring

pattern (?s)^\s*(\S.*\S|\S)\s*$

evaluatorsarray of object

Show child attributes

Show array items

configobjectrequired

namestringrequired

minLength 1

typestringrequired

one of "llm_judge", "code_metric"

execution_policyobject

Show child attributes

pass_thresholdinteger · int32

maximum 100 · minimum 1

runs_per_iteminteger · int32

maximum 100 · minimum 1

idstring · uuid

Stable item identifier. On write, used as the upsert key. If omitted, a new ID is generated. Remains the same across dataset versions

sourcestringrequired

one of "manual", "trace", "span", "sdk"

span_idstring · uuid

tagsarray of string

uniqueItems true

Show child attributes

uniqueItems true

trace_idstring · uuid

project_idstring · uuid

Optional. Associates the batch with a project by ID. Takes precedence over project_name.

project_namestring

Optional. Associates the batch with a project by name. Ignored if project_id is provided.

pattern (?s)^\s*(\S.*\S|\S)\s*$

Example request

{
  "batch_group_id": "00000000-0000-0000-0000-000000000000",
  "copy_from_dataset_id": "00000000-0000-0000-0000-000000000000",
  "copy_from_version_id": "00000000-0000-0000-0000-000000000000",
  "dataset_id": "00000000-0000-0000-0000-000000000000",
  "dataset_name": "string",
  "items": [
    {
      "data": {},
      "description": "string",
      "evaluators": [
        {
          "config": {},
          "name": "string",
          "type": "code_metric"
        }
      ],
      "execution_policy": {
        "pass_threshold": 0,
        "runs_per_item": 0
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "source": "manual",
      "span_id": "00000000-0000-0000-0000-000000000000",
      "tags": [
        "string"
      ],
      "trace_id": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "project_id": "00000000-0000-0000-0000-000000000000",
  "project_name": "string"
}

Responses

Examples

curl -X PUT 'http://localhost:5173/api/v1/private/datasets/items' \
  -H 'Content-Type: application/json' \
  -d '{"batch_group_id":"00000000-0000-0000-0000-000000000000","copy_from_dataset_id":"00000000-0000-0000-0000-000000000000","copy_from_version_id":"00000000-0000-0000-0000-000000000000","dataset_id":"00000000-0000-0000-0000-000000000000","dataset_name":"string","items":[{"data":{},"description":"string","evaluators":[{"config":{},"name":"string","type":"code_metric"}],"execution_policy":{"pass_threshold":0,"runs_per_item":0},"id":"00000000-0000-0000-0000-000000000000","source":"manual","span_id":"00000000-0000-0000-0000-000000000000","tags":["string"],"trace_id":"00000000-0000-0000-0000-000000000000"}],"project_id":"00000000-0000-0000-0000-000000000000","project_name":"string"}'

const response = await fetch('http://localhost:5173/api/v1/private/datasets/items', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"batch_group_id":"00000000-0000-0000-0000-000000000000","copy_from_dataset_id":"00000000-0000-0000-0000-000000000000","copy_from_version_id":"00000000-0000-0000-0000-000000000000","dataset_id":"00000000-0000-0000-0000-000000000000","dataset_name":"string","items":[{"data":{},"description":"string","evaluators":[{"config":{},"name":"string","type":"code_metric"}],"execution_policy":{"pass_threshold":0,"runs_per_item":0},"id":"00000000-0000-0000-0000-000000000000","source":"manual","span_id":"00000000-0000-0000-0000-000000000000","tags":["string"],"trace_id":"00000000-0000-0000-0000-000000000000"}],"project_id":"00000000-0000-0000-0000-000000000000","project_name":"string"}),
});
const data = await response.json();

const response = await fetch('http://localhost:5173/api/v1/private/datasets/items', { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: "{\"batch_group_id\":\"00000000-0000-0000-0000-000000000000\",\"copy_from_dataset_id\":\"00000000-0000-0000-0000-000000000000\",\"copy_from_version_id\":\"00000000-0000-0000-0000-000000000000\",\"dataset_id\":\"00000000-0000-0000-0000-000000000000\",\"dataset_name\":\"string\",\"items\":[{\"data\":{},\"description\":\"string\",\"evaluators\":[{\"config\":{},\"name\":\"string\",\"type\":\"code_metric\"}],\"execution_policy\":{\"pass_threshold\":0,\"runs_per_item\":0},\"id\":\"00000000-0000-0000-0000-000000000000\",\"source\":\"manual\",\"span_id\":\"00000000-0000-0000-0000-000000000000\",\"tags\":[\"string\"],\"trace_id\":\"00000000-0000-0000-0000-000000000000\"}],\"project_id\":\"00000000-0000-0000-0000-000000000000\",\"project_name\":\"string\"}" });
console.log(await response.json());

import requests

response = requests.request(
    "PUT",
    "http://localhost:5173/api/v1/private/datasets/items",
    headers={"Content-Type": "application/json"},
    data='{"batch_group_id":"00000000-0000-0000-0000-000000000000","copy_from_dataset_id":"00000000-0000-0000-0000-000000000000","copy_from_version_id":"00000000-0000-0000-0000-000000000000","dataset_id":"00000000-0000-0000-0000-000000000000","dataset_name":"string","items":[{"data":{},"description":"string","evaluators":[{"config":{},"name":"string","type":"code_metric"}],"execution_policy":{"pass_threshold":0,"runs_per_item":0},"id":"00000000-0000-0000-0000-000000000000","source":"manual","span_id":"00000000-0000-0000-0000-000000000000","tags":["string"],"trace_id":"00000000-0000-0000-0000-000000000000"}],"project_id":"00000000-0000-0000-0000-000000000000","project_name":"string"}',
)
print(response.json())

package main

import (
	"context"
	"net/http"
	"strings"
)

func main() {
	ctx := context.Background()
	body := strings.NewReader(`{"batch_group_id":"00000000-0000-0000-0000-000000000000","copy_from_dataset_id":"00000000-0000-0000-0000-000000000000","copy_from_version_id":"00000000-0000-0000-0000-000000000000","dataset_id":"00000000-0000-0000-0000-000000000000","dataset_name":"string","items":[{"data":{},"description":"string","evaluators":[{"config":{},"name":"string","type":"code_metric"}],"execution_policy":{"pass_threshold":0,"runs_per_item":0},"id":"00000000-0000-0000-0000-000000000000","source":"manual","span_id":"00000000-0000-0000-0000-000000000000","tags":["string"],"trace_id":"00000000-0000-0000-0000-000000000000"}],"project_id":"00000000-0000-0000-0000-000000000000","project_name":"string"}`)
	req, err := http.NewRequestWithContext(ctx, "PUT", "http://localhost:5173/api/v1/private/datasets/items", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

<?php
$request = curl_init("http://localhost:5173/api/v1/private/datasets/items");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"batch_group_id\":\"00000000-0000-0000-0000-000000000000\",\"copy_from_dataset_id\":\"00000000-0000-0000-0000-000000000000\",\"copy_from_version_id\":\"00000000-0000-0000-0000-000000000000\",\"dataset_id\":\"00000000-0000-0000-0000-000000000000\",\"dataset_name\":\"string\",\"items\":[{\"data\":{},\"description\":\"string\",\"evaluators\":[{\"config\":{},\"name\":\"string\",\"type\":\"code_metric\"}],\"execution_policy\":{\"pass_threshold\":0,\"runs_per_item\":0},\"id\":\"00000000-0000-0000-0000-000000000000\",\"source\":\"manual\",\"span_id\":\"00000000-0000-0000-0000-000000000000\",\"tags\":[\"string\"],\"trace_id\":\"00000000-0000-0000-0000-000000000000\"}],\"project_id\":\"00000000-0000-0000-0000-000000000000\",\"project_name\":\"string\"}");
curl_setopt($request, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("http://localhost:5173/api/v1/private/datasets/items"))
    .method("PUT", HttpRequest.BodyPublishers.noBody())
    .header("Content-Type", "application/json")
    .method("PUT", HttpRequest.BodyPublishers.ofString("{\"batch_group_id\":\"00000000-0000-0000-0000-000000000000\",\"copy_from_dataset_id\":\"00000000-0000-0000-0000-000000000000\",\"copy_from_version_id\":\"00000000-0000-0000-0000-000000000000\",\"dataset_id\":\"00000000-0000-0000-0000-000000000000\",\"dataset_name\":\"string\",\"items\":[{\"data\":{},\"description\":\"string\",\"evaluators\":[{\"config\":{},\"name\":\"string\",\"type\":\"code_metric\"}],\"execution_policy\":{\"pass_threshold\":0,\"runs_per_item\":0},\"id\":\"00000000-0000-0000-0000-000000000000\",\"source\":\"manual\",\"span_id\":\"00000000-0000-0000-0000-000000000000\",\"tags\":[\"string\"],\"trace_id\":\"00000000-0000-0000-0000-000000000000\"}],\"project_id\":\"00000000-0000-0000-0000-000000000000\",\"project_name\":\"string\"}"))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("http://localhost:5173/api/v1/private/datasets/items")
request = Net::HTTPGenericRequest.new("PUT", true, true, uri)
request['Content-Type'] = 'application/json'
request.body = "{\"batch_group_id\":\"00000000-0000-0000-0000-000000000000\",\"copy_from_dataset_id\":\"00000000-0000-0000-0000-000000000000\",\"copy_from_version_id\":\"00000000-0000-0000-0000-000000000000\",\"dataset_id\":\"00000000-0000-0000-0000-000000000000\",\"dataset_name\":\"string\",\"items\":[{\"data\":{},\"description\":\"string\",\"evaluators\":[{\"config\":{},\"name\":\"string\",\"type\":\"code_metric\"}],\"execution_policy\":{\"pass_threshold\":0,\"runs_per_item\":0},\"id\":\"00000000-0000-0000-0000-000000000000\",\"source\":\"manual\",\"span_id\":\"00000000-0000-0000-0000-000000000000\",\"tags\":[\"string\"],\"trace_id\":\"00000000-0000-0000-0000-000000000000\"}],\"project_id\":\"00000000-0000-0000-0000-000000000000\",\"project_name\":\"string\"}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Put, "http://localhost:5173/api/v1/private/datasets/items");
request.Content = new StringContent("{\"batch_group_id\":\"00000000-0000-0000-0000-000000000000\",\"copy_from_dataset_id\":\"00000000-0000-0000-0000-000000000000\",\"copy_from_version_id\":\"00000000-0000-0000-0000-000000000000\",\"dataset_id\":\"00000000-0000-0000-0000-000000000000\",\"dataset_name\":\"string\",\"items\":[{\"data\":{},\"description\":\"string\",\"evaluators\":[{\"config\":{},\"name\":\"string\",\"type\":\"code_metric\"}],\"execution_policy\":{\"pass_threshold\":0,\"runs_per_item\":0},\"id\":\"00000000-0000-0000-0000-000000000000\",\"source\":\"manual\",\"span_id\":\"00000000-0000-0000-0000-000000000000\",\"tags\":[\"string\"],\"trace_id\":\"00000000-0000-0000-0000-000000000000\"}],\"project_id\":\"00000000-0000-0000-0000-000000000000\",\"project_name\":\"string\"}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

(no response body — HTTP 204)