Scale AI Datasets API

openapi: 3.2.0
info:
  title: EGP API V5 Datasets 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: Datasets
paths:
  /v5/datasets/{dataset_id}:
    delete:
      tags:
      - Datasets
      summary: Archive a dataset
      description: 'Soft-delete a dataset by archiving it; the row is retained and can be restored later.


        This sets the dataset''s `archived_at` timestamp rather than permanently removing it, and

        cascades the same archival to the dataset''s items and versions. Archiving is not idempotent:

        if the dataset is already archived the call fails. The dataset can be brought back with the

        PATCH restore request. The response reports the dataset id with `deleted` set to true.'
      operationId: DELETE-V5-/v5/datasets/dataset_id
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          title: Dataset Id
          type: string
      - 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_Dataset_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/datasets/archive-a-dataset
    get:
      tags:
      - Datasets
      summary: Get a dataset
      description: 'Retrieve a single dataset by its id.


        By default an archived dataset is not returned; set `include_archived` to true to fetch a

        dataset regardless of whether it has been archived.'
      operationId: GET-V5-/v5/datasets/dataset_id
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          title: Dataset Id
          type: string
      - name: include_archived
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Archived
      - 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/Dataset'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/datasets/get-a-dataset
    patch:
      tags:
      - Datasets
      summary: Update or restore a dataset
      description: 'Update a dataset''s fields, or restore a previously archived dataset.


        The request body is a union discriminated by its contents: a body of `{"restore": true}`

        triggers a restore, and any other body is treated as a partial update of the dataset''s `name`,

        `description`, and `tags`. Restore clears `archived_at` on the dataset and cascades the

        un-archival to its items and versions; restoring a dataset that is not archived returns it

        unchanged. A partial update on an archived dataset fails, since archived datasets cannot be

        modified.'
      operationId: PATCH-V5-/v5/datasets/dataset_id
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          title: Dataset Id
          type: string
      - 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/DatasetUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/datasets/update-or-restore-a-dataset
  /v5/datasets:
    post:
      tags:
      - Datasets
      summary: Create a dataset
      description: 'Create a dataset and populate it with its initial items in a single call.


        Use this when the dataset does not exist yet: it creates the dataset and seeds it with the

        items you provide. To add more items to a dataset that already exists, use

        POST /v5/dataset-items/batch instead. A name is required, and the request must include at

        least one item in `data`; the optional `files` field associates files with the created items.

        The provided items are inserted as dataset items as a side effect of creation, and any `tags`

        are attached to the dataset. The returned dataset is at version 1.'
      operationId: POST-V5-/v5/datasets
      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/DatasetCreateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/datasets/create-a-dataset
    get:
      tags:
      - Datasets
      summary: List datasets
      description: 'Return a paginated list of the account''s datasets.


        Archived datasets are excluded unless `include_archived` is set to true. Results can be

        narrowed by `tags` and by the standard filterable parameters; a `name` filter matches as a

        case-insensitive substring rather than an exact match.'
      operationId: GET-V5-/v5/datasets
      parameters:
      - name: tags
        in: query
        required: false
        schema:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
      - name: include_archived
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Archived
      - 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: name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
      - 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_Dataset_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/datasets/list-datasets
components:
  schemas:
    DatasetUpdateRequest:
      anyOf:
      - $ref: '#/components/schemas/PartialDatasetRequestBase'
      - $ref: '#/components/schemas/RestoreRequest'
      title: DatasetUpdateRequest
    DeleteResponse_Dataset_:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: dataset
          title: Object
          default: dataset
        deleted:
          type: boolean
          title: Deleted
      type: object
      required:
      - id
      - deleted
    PartialDatasetRequestBase:
      properties:
        name:
          type: string
          title: Name
        description:
          title: Description
          type: string
        tags:
          title: Tags
          description: The tags associated with the entity
          items:
            type: string
          type: array
      additionalProperties: false
      type: object
      title: PartialDatasetRequestBase
    IdentityType:
      type: string
      enum:
      - user
      - service_account
      title: IdentityType
    SortOrder:
      type: string
      enum:
      - asc
      - desc
      title: SortOrder
    PaginatedList_Dataset_:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        items:
          items:
            $ref: '#/components/schemas/Dataset'
          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
    DatasetCreateRequest:
      properties:
        name:
          type: string
          title: Name
        description:
          title: Description
          type: string
        tags:
          title: Tags
          description: The tags associated with the entity
          items:
            type: string
          type: array
        data:
          items:
            additionalProperties: true
            type: object
          type: array
          minItems: 1
          title: Data
          description: Items to be included in 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:
      - name
      - data
      title: DatasetCreateRequest
    Dataset:
      properties:
        id:
          type: string
          title: Id
          description: The unique identifier of the entity.
        object:
          type: string
          const: dataset
          title: Object
          default: dataset
        created_by:
          $ref: '#/components/schemas/Identity'
          description: The identity that created the entity.
        name:
          type: string
          title: Name
        description:
          title: Description
          type: string
        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
        tags:
          title: Tags
          description: The tags associated with the entity
          items:
            type: string
          type: array
        current_version_num:
          type: integer
          title: Current Version Num
      type: object
      required:
      - created_by
      - name
      - id
      - created_at
      - tags
      - current_version_num
    RestoreRequest:
      properties:
        restore:
          type: boolean
          const: true
          title: Restore
          description: Set to true to restore the entity from the database.
      additionalProperties: false
      type: object
      required:
      - restore
      title: RestoreRequest
    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
  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)