Scale AI Dataset Items API

openapi: 3.2.0
info:
  title: EGP API V5 Dataset Items API
  description: This is the parent API for all EGP APIs. If you are looking for the EGP API, please go to https://api.egp.scale.com/docs.
  contact:
    name: Scale Generative AI Platform
    url: https://scale.com/genai-platform
  version: 0.1.0
servers:
- url: https://api.egp.scale.com
security: []
tags:
- name: Dataset Items
paths:
  /v5/dataset-items/batch:
    post:
      tags:
      - Dataset Items
      summary: Add items to an existing dataset
      description: '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.'
      operationId: POST-V5-/v5/dataset-items/batch
      parameters:
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetItemBatchCreateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIList_DatasetItem_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/dataset-items/add-items-to-an-existing-dataset
  /v5/dataset-items/{dataset_item_id}:
    delete:
      tags:
      - Dataset Items
      summary: Delete a dataset item
      description: '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.'
      operationId: DELETE-V5-/v5/dataset-items/dataset_item_id
      parameters:
      - name: dataset_item_id
        in: path
        required: true
        schema:
          type: string
          title: Dataset Item Id
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse_DatasetItem_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/dataset-items/delete-a-dataset-item
    get:
      tags:
      - Dataset Items
      summary: Get a dataset item
      description: '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.'
      operationId: GET-V5-/v5/dataset-items/dataset_item_id
      parameters:
      - name: dataset_item_id
        in: path
        required: true
        schema:
          type: string
          title: Dataset Item Id
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Optional dataset version. When unset, returns the latest version.
          title: Version
        description: Optional dataset version. When unset, returns the latest version.
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetItem'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/dataset-items/get-a-dataset-item
    patch:
      tags:
      - Dataset Items
      summary: Update a dataset item
      description: '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.'
      operationId: PATCH-V5-/v5/dataset-items/dataset_item_id
      parameters:
      - name: dataset_item_id
        in: path
        required: true
        schema:
          type: string
          title: Dataset Item Id
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetItemUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetItem'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/dataset-items/update-a-dataset-item
  /v5/dataset-items:
    get:
      tags:
      - Dataset Items
      summary: List dataset items
      description: '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.'
      operationId: GET-V5-/v5/dataset-items
      parameters:
      - name: include_archived
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Archived
      - name: dataset_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional dataset identifier. Must be provided if a specific version is requested.
          title: Dataset Id
        description: Optional dataset identifier. Must be provided if a specific version is requested.
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Optional dataset version. When unset, returns the latest version. Requires a valid dataset_id when set.
          title: Version
        description: Optional dataset version. When unset, returns the latest version. Requires a valid dataset_id when set.
      - name: starting_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Starting After
      - name: ending_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Ending Before
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 10000
          minimum: 1
          default: 100
          title: Limit
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Sort By
      - name: sort_order
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/SortOrder'
          - type: 'null'
          default: asc
          title: Sort Order
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList_DatasetItem_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/dataset-items/list-dataset-items
components:
  schemas:
    DatasetItem:
      properties:
        id:
          type: string
          title: Id
          description: The unique identifier of the entity.
        object:
          type: string
          const: dataset.item
          title: Object
          default: dataset.item
        created_by:
          $ref: '#/components/schemas/Identity'
          description: The identity that created the entity.
        dataset_id:
          title: Dataset Id
          type: string
        data:
          additionalProperties: true
          type: object
          title: Data
        files:
          title: Files
          additionalProperties:
            type: string
          type: object
        content_hash:
          type: string
          title: Content Hash
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The date and time when the entity was created in ISO format.
        archived_at:
          title: Archived At
          description: The date and time when the entity was archived in ISO format.
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: The date and time when the entity was last updated in ISO format.
      type: object
      required:
      - created_by
      - data
      - content_hash
      - id
      - created_at
      - updated_at
    IdentityType:
      type: string
      enum:
      - user
      - service_account
      title: IdentityType
    APIList_DatasetItem_:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        items:
          items:
            $ref: '#/components/schemas/DatasetItem'
          type: array
          title: Items
      type: object
      required:
      - items
    DatasetItemBatchCreateRequest:
      properties:
        dataset_id:
          type: string
          title: Dataset Id
          description: Identifier of the target dataset
        data:
          items:
            additionalProperties: true
            type: object
          type: array
          minItems: 1
          title: Data
          description: Items to be added to the dataset
        files:
          title: Files
          description: Files to be associated to the dataset
          items:
            additionalProperties:
              type: string
            type: object
          type: array
          minItems: 1
      type: object
      required:
      - dataset_id
      - data
      title: DatasetItemBatchCreateRequest
    PaginatedList_DatasetItem_:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        items:
          items:
            $ref: '#/components/schemas/DatasetItem'
          type: array
          title: Items
        limit:
          type: integer
          title: Limit
          description: The maximum number of items to return.
          default: 100
        total:
          type: integer
          title: Total
          description: The total of items that match the query. This is greater than or equal to the number of items returned.
        has_more:
          type: boolean
          title: Has More
          description: Whether there are more items left to be fetched.
      type: object
      required:
      - items
      - total
      - has_more
    DatasetItemUpdateRequest:
      properties:
        data:
          additionalProperties: true
          type: object
          title: Data
          description: Updated dataset item data
        files:
          title: Files
          description: Files to be associated to the dataset
          additionalProperties:
            type: string
          type: object
          minProperties: 1
      type: object
      required:
      - data
      title: DatasetItemUpdateRequest
    DeleteResponse_DatasetItem_:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: dataset.item
          title: Object
          default: dataset.item
        deleted:
          type: boolean
          title: Deleted
      type: object
      required:
      - id
      - deleted
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          title: Error Type
          type: string
        input:
          title: Input
        ctx:
          type: object
          title: Context
          additionalProperties: true
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Identity:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: identity
          title: Object
          default: identity
        type:
          $ref: '#/components/schemas/IdentityType'
      type: object
      required:
      - id
      - type
      title: Identity
    SortOrder:
      type: string
      enum:
      - asc
      - desc
      title: SortOrder
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
x-assembled-from: Per-operation OpenAPI fragments embedded verbatim in docs.gp.scale.com reference pages; source spec https://api.sgp.scale.com/openapi-versions/v5/openapi.json (404 when assembled)