# Dataset Items ## Add items to an existing dataset `client.DatasetItems.BatchNew(ctx, body) (*DatasetItemBatchNewResponse, error)` **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. ### Parameters - `body DatasetItemBatchNewParams` - `Data param.Field[[]map[string, any]]` Items to be added to the dataset - `DatasetID param.Field[string]` Identifier of the target dataset - `Files param.Field[[]map[string, string]]` Files to be associated to the dataset ### Returns - `type DatasetItemBatchNewResponse struct{…}` - `Items []DatasetItem` - `ID string` The unique identifier of the entity. - `ContentHash string` - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `Data map[string, any]` - `UpdatedAt Time` The date and time when the entity was last updated in ISO format. - `ArchivedAt Time` The date and time when the entity was archived in ISO format. - `DatasetID string` - `Files map[string, string]` - `Object DatasetItemObject` - `const DatasetItemObjectDatasetItem DatasetItemObject = "dataset.item"` - `Object DatasetItemBatchNewResponseObject` - `const DatasetItemBatchNewResponseObjectList DatasetItemBatchNewResponseObject = "list"` ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) response, err := client.DatasetItems.BatchNew(context.TODO(), sgpdev.DatasetItemBatchNewParams{ Data: []map[string]any{map[string]any{ "foo": "bar", }}, DatasetID: "dataset_id", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.Items) } ``` #### 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 `client.DatasetItems.Get(ctx, datasetItemID, query) (*DatasetItem, error)` **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. ### Parameters - `datasetItemID string` - `query DatasetItemGetParams` - `Version param.Field[int64]` Optional dataset version. When unset, returns the latest version. ### Returns - `type DatasetItem struct{…}` - `ID string` The unique identifier of the entity. - `ContentHash string` - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `Data map[string, any]` - `UpdatedAt Time` The date and time when the entity was last updated in ISO format. - `ArchivedAt Time` The date and time when the entity was archived in ISO format. - `DatasetID string` - `Files map[string, string]` - `Object DatasetItemObject` - `const DatasetItemObjectDatasetItem DatasetItemObject = "dataset.item"` ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) datasetItem, err := client.DatasetItems.Get( context.TODO(), "dataset_item_id", sgpdev.DatasetItemGetParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", datasetItem.ID) } ``` #### 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 `client.DatasetItems.Archive(ctx, datasetItemID) (*DatasetItemArchiveResponse, error)` **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. ### Parameters - `datasetItemID string` ### Returns - `type DatasetItemArchiveResponse struct{…}` - `ID string` - `Deleted bool` - `Object DatasetItemArchiveResponseObject` - `const DatasetItemArchiveResponseObjectDatasetItem DatasetItemArchiveResponseObject = "dataset.item"` ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) response, err := client.DatasetItems.Archive(context.TODO(), "dataset_item_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.ID) } ``` #### Response ```json { "id": "id", "deleted": true, "object": "dataset.item" } ``` ## Update a dataset item `client.DatasetItems.Update(ctx, datasetItemID, body) (*DatasetItem, error)` **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. ### Parameters - `datasetItemID string` - `body DatasetItemUpdateParams` - `Data param.Field[map[string, any]]` Updated dataset item data - `Files param.Field[map[string, string]]` Files to be associated to the dataset ### Returns - `type DatasetItem struct{…}` - `ID string` The unique identifier of the entity. - `ContentHash string` - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `Data map[string, any]` - `UpdatedAt Time` The date and time when the entity was last updated in ISO format. - `ArchivedAt Time` The date and time when the entity was archived in ISO format. - `DatasetID string` - `Files map[string, string]` - `Object DatasetItemObject` - `const DatasetItemObjectDatasetItem DatasetItemObject = "dataset.item"` ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) datasetItem, err := client.DatasetItems.Update( context.TODO(), "dataset_item_id", sgpdev.DatasetItemUpdateParams{ Data: map[string]any{ "foo": "bar", }, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", datasetItem.ID) } ``` #### 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 `client.DatasetItems.List(ctx, query) (*CursorPage[DatasetItem], error)` **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. ### Parameters - `query DatasetItemListParams` - `DatasetID param.Field[string]` Optional dataset identifier. Must be provided if a specific version is requested. - `EndingBefore param.Field[string]` - `IncludeArchived param.Field[bool]` - `Limit param.Field[int64]` - `SortBy param.Field[string]` - `SortOrder param.Field[SortOrder]` - `StartingAfter param.Field[string]` - `Version param.Field[int64]` Optional dataset version. When unset, returns the latest version. Requires a valid dataset_id when set. ### Returns - `type DatasetItem struct{…}` - `ID string` The unique identifier of the entity. - `ContentHash string` - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `Data map[string, any]` - `UpdatedAt Time` The date and time when the entity was last updated in ISO format. - `ArchivedAt Time` The date and time when the entity was archived in ISO format. - `DatasetID string` - `Files map[string, string]` - `Object DatasetItemObject` - `const DatasetItemObjectDatasetItem DatasetItemObject = "dataset.item"` ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) page, err := client.DatasetItems.List(context.TODO(), sgpdev.DatasetItemListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### 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 - `type DatasetItem struct{…}` - `ID string` The unique identifier of the entity. - `ContentHash string` - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `Data map[string, any]` - `UpdatedAt Time` The date and time when the entity was last updated in ISO format. - `ArchivedAt Time` The date and time when the entity was archived in ISO format. - `DatasetID string` - `Files map[string, string]` - `Object DatasetItemObject` - `const DatasetItemObjectDatasetItem DatasetItemObject = "dataset.item"`