# Dataset Items

## Add items to an existing dataset

**post** `/v5/dataset-items/batch`

Add one or more items in a single batch to a dataset that already exists.

Use this to append items to an existing dataset; to create a dataset together with its initial
items in one call, use POST /v5/datasets instead (this endpoint does not create datasets).
Items are only ever added in a batch — there is no single-item create endpoint. The target
dataset is identified by the required dataset_id in the request body, and each entry in data
(at least one is required) becomes one item, optionally paired with the files entry at the same
list index — when files is supplied it must be the same length as data. Each referenced file
must exist and be a supported media format, and item keys may not collide with reserved dataset-
or evaluation-item field names. The target dataset must not be archived. The batch is applied as
a new dataset version snapshot rather than mutating existing versions, and the created items are
returned.

### Body Parameters

- `data: array of map[unknown]`

  Items to be added to the dataset

- `dataset_id: string`

  Identifier of the target dataset

- `files: optional array of map[string]`

  Files to be associated to the dataset

### Returns

- `items: array of DatasetItem`

  - `id: string`

    The unique identifier of the entity.

  - `content_hash: string`

  - `created_at: string`

    The date and time when the entity was created in ISO format.

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `data: map[unknown]`

  - `updated_at: string`

    The date and time when the entity was last updated in ISO format.

  - `archived_at: optional string`

    The date and time when the entity was archived in ISO format.

  - `dataset_id: optional string`

  - `files: optional map[string]`

  - `object: optional "dataset.item"`

    - `"dataset.item"`

- `object: optional "list"`

  - `"list"`

### Example

```http
curl https://api.egp.scale.com/v5/dataset-items/batch \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $SGP_API_KEY" \
    -d '{
          "data": [
            {
              "foo": "bar"
            }
          ],
          "dataset_id": "dataset_id"
        }'
```

#### Response

```json
{
  "items": [
    {
      "id": "id",
      "content_hash": "content_hash",
      "created_at": "2019-12-27T18:11:19.117Z",
      "created_by": {
        "id": "id",
        "type": "user",
        "object": "identity"
      },
      "data": {
        "foo": "bar"
      },
      "updated_at": "2019-12-27T18:11:19.117Z",
      "archived_at": "2019-12-27T18:11:19.117Z",
      "dataset_id": "dataset_id",
      "files": {
        "foo": "string"
      },
      "object": "dataset.item"
    }
  ],
  "object": "list"
}
```

## Get a dataset item

**get** `/v5/dataset-items/{dataset_item_id}`

Retrieve a single dataset item by its identifier.

The lookup is scoped to the caller's account. By default the current (latest) version of the item
is returned; passing version returns the item as it existed at that dataset version, which allows
reading an item that was later updated or soft-deleted.

### Path Parameters

- `dataset_item_id: string`

### Query Parameters

- `version: optional number`

  Optional dataset version. When unset, returns the latest version.

### Returns

- `DatasetItem object { id, content_hash, created_at, 7 more }`

  - `id: string`

    The unique identifier of the entity.

  - `content_hash: string`

  - `created_at: string`

    The date and time when the entity was created in ISO format.

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `data: map[unknown]`

  - `updated_at: string`

    The date and time when the entity was last updated in ISO format.

  - `archived_at: optional string`

    The date and time when the entity was archived in ISO format.

  - `dataset_id: optional string`

  - `files: optional map[string]`

  - `object: optional "dataset.item"`

    - `"dataset.item"`

### Example

```http
curl https://api.egp.scale.com/v5/dataset-items/$DATASET_ITEM_ID \
    -H "x-api-key: $SGP_API_KEY"
```

#### Response

```json
{
  "id": "id",
  "content_hash": "content_hash",
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "data": {
    "foo": "bar"
  },
  "updated_at": "2019-12-27T18:11:19.117Z",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "dataset_id": "dataset_id",
  "files": {
    "foo": "string"
  },
  "object": "dataset.item"
}
```

## Delete a dataset item

**delete** `/v5/dataset-items/{dataset_item_id}`

Soft-delete a dataset item by marking it as removed in the current dataset version.

The database row is not removed; instead the item's end version is set to the current dataset
version so it no longer appears at the latest version while remaining retrievable at earlier
versions, and a new dataset version snapshot is created to record the removal. An item that is
already archived or already deleted cannot be deleted again. The response echoes the item id with
deleted set to true.

### Path Parameters

- `dataset_item_id: string`

### Returns

- `id: string`

- `deleted: boolean`

- `object: optional "dataset.item"`

  - `"dataset.item"`

### Example

```http
curl https://api.egp.scale.com/v5/dataset-items/$DATASET_ITEM_ID \
    -X DELETE \
    -H "x-api-key: $SGP_API_KEY"
```

#### Response

```json
{
  "id": "id",
  "deleted": true,
  "object": "dataset.item"
}
```

## Update a dataset item

**patch** `/v5/dataset-items/{dataset_item_id}`

Update the data payload and optional file associations of a dataset item.

The request replaces the item's data in full and, if provided, its file associations; there is no
partial-field merge. Data keys may not collide with reserved dataset- or evaluation-item field
names, and any referenced files must exist and be a supported media format. Items that are
archived or soft-deleted cannot be updated. The update is applied as a new dataset version rather
than overwriting the previous record, so prior versions remain retrievable.

### Path Parameters

- `dataset_item_id: string`

### Body Parameters

- `data: map[unknown]`

  Updated dataset item data

- `files: optional map[string]`

  Files to be associated to the dataset

### Returns

- `DatasetItem object { id, content_hash, created_at, 7 more }`

  - `id: string`

    The unique identifier of the entity.

  - `content_hash: string`

  - `created_at: string`

    The date and time when the entity was created in ISO format.

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `data: map[unknown]`

  - `updated_at: string`

    The date and time when the entity was last updated in ISO format.

  - `archived_at: optional string`

    The date and time when the entity was archived in ISO format.

  - `dataset_id: optional string`

  - `files: optional map[string]`

  - `object: optional "dataset.item"`

    - `"dataset.item"`

### Example

```http
curl https://api.egp.scale.com/v5/dataset-items/$DATASET_ITEM_ID \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $SGP_API_KEY" \
    -d '{
          "data": {
            "foo": "bar"
          }
        }'
```

#### Response

```json
{
  "id": "id",
  "content_hash": "content_hash",
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "data": {
    "foo": "bar"
  },
  "updated_at": "2019-12-27T18:11:19.117Z",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "dataset_id": "dataset_id",
  "files": {
    "foo": "string"
  },
  "object": "dataset.item"
}
```

## List dataset items

**get** `/v5/dataset-items`

List dataset items belonging to the caller's account, paginated.

dataset_id is optional: when omitted, items across all of the account's datasets are returned;
when provided, results are restricted to that dataset. A specific version may be requested only
together with a dataset_id — passing version without dataset_id is rejected. By default only
current items at the latest version are listed (soft-deleted items are excluded); archived items
are excluded unless include_archived is true.

### Query Parameters

- `dataset_id: optional string`

  Optional dataset identifier. Must be provided if a specific version is requested.

- `ending_before: optional string`

- `include_archived: optional boolean`

- `limit: optional number`

- `sort_by: optional string`

- `sort_order: optional SortOrder`

  - `"asc"`

  - `"desc"`

- `starting_after: optional string`

- `version: optional number`

  Optional dataset version. When unset, returns the latest version. Requires a valid dataset_id when set.

### Returns

- `has_more: boolean`

  Whether there are more items left to be fetched.

- `items: array of DatasetItem`

  - `id: string`

    The unique identifier of the entity.

  - `content_hash: string`

  - `created_at: string`

    The date and time when the entity was created in ISO format.

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `data: map[unknown]`

  - `updated_at: string`

    The date and time when the entity was last updated in ISO format.

  - `archived_at: optional string`

    The date and time when the entity was archived in ISO format.

  - `dataset_id: optional string`

  - `files: optional map[string]`

  - `object: optional "dataset.item"`

    - `"dataset.item"`

- `total: number`

  The total of items that match the query. This is greater than or equal to the number of items returned.

- `limit: optional number`

  The maximum number of items to return.

- `object: optional "list"`

  - `"list"`

### Example

```http
curl https://api.egp.scale.com/v5/dataset-items \
    -H "x-api-key: $SGP_API_KEY"
```

#### Response

```json
{
  "has_more": true,
  "items": [
    {
      "id": "id",
      "content_hash": "content_hash",
      "created_at": "2019-12-27T18:11:19.117Z",
      "created_by": {
        "id": "id",
        "type": "user",
        "object": "identity"
      },
      "data": {
        "foo": "bar"
      },
      "updated_at": "2019-12-27T18:11:19.117Z",
      "archived_at": "2019-12-27T18:11:19.117Z",
      "dataset_id": "dataset_id",
      "files": {
        "foo": "string"
      },
      "object": "dataset.item"
    }
  ],
  "total": 0,
  "limit": 0,
  "object": "list"
}
```

## Domain Types

### Dataset Item

- `DatasetItem object { id, content_hash, created_at, 7 more }`

  - `id: string`

    The unique identifier of the entity.

  - `content_hash: string`

  - `created_at: string`

    The date and time when the entity was created in ISO format.

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `data: map[unknown]`

  - `updated_at: string`

    The date and time when the entity was last updated in ISO format.

  - `archived_at: optional string`

    The date and time when the entity was archived in ISO format.

  - `dataset_id: optional string`

  - `files: optional map[string]`

  - `object: optional "dataset.item"`

    - `"dataset.item"`

### Dataset Item Batch Create Response

- `DatasetItemBatchCreateResponse object { items, object }`

  - `items: array of DatasetItem`

    - `id: string`

      The unique identifier of the entity.

    - `content_hash: string`

    - `created_at: string`

      The date and time when the entity was created in ISO format.

    - `created_by: Identity`

      The identity that created the entity.

      - `id: string`

      - `type: "user" or "service_account"`

        - `"user"`

        - `"service_account"`

      - `object: optional "identity"`

        - `"identity"`

    - `data: map[unknown]`

    - `updated_at: string`

      The date and time when the entity was last updated in ISO format.

    - `archived_at: optional string`

      The date and time when the entity was archived in ISO format.

    - `dataset_id: optional string`

    - `files: optional map[string]`

    - `object: optional "dataset.item"`

      - `"dataset.item"`

  - `object: optional "list"`

    - `"list"`

### Dataset Item Archive Response

- `DatasetItemArchiveResponse object { id, deleted, object }`

  - `id: string`

  - `deleted: boolean`

  - `object: optional "dataset.item"`

    - `"dataset.item"`