ArthurAI Datasets API

openapi: 3.2.0
info:
  title: Arthur GenAI Engine Agent Discovery Datasets API
  version: 2.1.688
servers:
- url: https://platform.arthur.ai/api
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Datasets
paths:
  /api/v2/tasks/{task_id}/datasets:
    post:
      tags:
      - Datasets
      summary: Create Dataset
      description: Register a new dataset.
      operationId: create_dataset_api_v2_tasks__task_id__datasets_post
      security:
      - API Key: []
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Task Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewDatasetRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/datasets/{dataset_id}:
    patch:
      tags:
      - Datasets
      summary: Update Dataset
      description: Update a dataset.
      operationId: update_dataset_api_v2_datasets__dataset_id__patch
      security:
      - API Key: []
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the dataset to update.
          title: Dataset Id
        description: ID of the dataset to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Datasets
      summary: Delete Dataset
      description: Delete a dataset.
      operationId: delete_dataset_api_v2_datasets__dataset_id__delete
      security:
      - API Key: []
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the dataset to delete.
          title: Dataset Id
        description: ID of the dataset to delete.
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Datasets
      summary: Get Dataset
      description: Get a dataset.
      operationId: get_dataset_api_v2_datasets__dataset_id__get
      security:
      - API Key: []
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the dataset to fetch.
          title: Dataset Id
        description: ID of the dataset to fetch.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/tasks/{task_id}/datasets/search:
    get:
      tags:
      - Datasets
      summary: Get Datasets
      description: Search datasets. Optionally can filter by dataset IDs and dataset name.
      operationId: get_datasets_api_v2_tasks__task_id__datasets_search_get
      security:
      - API Key: []
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Task Id
      - name: dataset_ids
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
              format: uuid
          - type: 'null'
          description: List of dataset ids to query for.
          title: Dataset Ids
        description: List of dataset ids to query for.
      - name: dataset_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Dataset name substring to search for.
          title: Dataset Name
        description: Dataset name substring to search for.
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PaginationSortMethod'
          description: Sort the results (asc/desc)
          default: desc
        description: Sort the results (asc/desc)
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          description: Page size. Default is 10. Must be greater than 0 and less than 5000.
          default: 10
          title: Page Size
        description: Page size. Default is 10. Must be greater than 0 and less than 5000.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          description: Page number
          default: 0
          title: Page
        description: Page number
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchDatasetsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/datasets/{dataset_id}/versions:
    post:
      tags:
      - Datasets
      summary: Create Dataset Version
      description: Create a new dataset version.
      operationId: create_dataset_version_api_v2_datasets__dataset_id__versions_post
      security:
      - API Key: []
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the dataset to create a new version for.
          title: Dataset Id
        description: ID of the dataset to create a new version for.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewDatasetVersionRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetVersionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Datasets
      summary: Get Dataset Versions
      description: List dataset versions.
      operationId: get_dataset_versions_api_v2_datasets__dataset_id__versions_get
      security:
      - API Key: []
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the dataset to fetch versions for.
          title: Dataset Id
        description: ID of the dataset to fetch versions for.
      - name: latest_version_only
        in: query
        required: false
        schema:
          type: boolean
          description: Whether to only include the latest version for the dataset in the response. Defaults to False.
          default: false
          title: Latest Version Only
        description: Whether to only include the latest version for the dataset in the response. Defaults to False.
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PaginationSortMethod'
          description: Sort the results (asc/desc)
          default: desc
        description: Sort the results (asc/desc)
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          description: Page size. Default is 10. Must be greater than 0 and less than 5000.
          default: 10
          title: Page Size
        description: Page size. Default is 10. Must be greater than 0 and less than 5000.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          description: Page number
          default: 0
          title: Page
        description: Page number
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDatasetVersionsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/datasets/{dataset_id}/versions/{version_number}:
    get:
      tags:
      - Datasets
      summary: Get Dataset Version
      description: Fetch a dataset version.
      operationId: get_dataset_version_api_v2_datasets__dataset_id__versions__version_number__get
      security:
      - API Key: []
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the dataset to fetch the version for.
          title: Dataset Id
        description: ID of the dataset to fetch the version for.
      - name: version_number
        in: path
        required: true
        schema:
          type: integer
          description: Version number to fetch.
          title: Version Number
        description: Version number to fetch.
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search query to filter rows. Performs case-insensitive search across all column values.
          title: Search
        description: Search query to filter rows. Performs case-insensitive search across all column values.
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PaginationSortMethod'
          description: Sort the results (asc/desc)
          default: desc
        description: Sort the results (asc/desc)
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          description: Page size. Default is 10. Must be greater than 0 and less than 5000.
          default: 10
          title: Page Size
        description: Page size. Default is 10. Must be greater than 0 and less than 5000.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          description: Page number
          default: 0
          title: Page
        description: Page number
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetVersionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/datasets/{dataset_id}/versions/{version_number}/rows/{row_id}:
    get:
      tags:
      - Datasets
      summary: Get Dataset Version Row
      description: Fetch a specific row from a dataset version by row ID.
      operationId: get_dataset_version_row_api_v2_datasets__dataset_id__versions__version_number__rows__row_id__get
      security:
      - API Key: []
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the dataset.
          title: Dataset Id
        description: ID of the dataset.
      - name: version_number
        in: path
        required: true
        schema:
          type: integer
          description: Version number of the dataset.
          title: Version Number
        description: Version number of the dataset.
      - name: row_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the row to fetch.
          title: Row Id
        description: ID of the row to fetch.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetVersionRowResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/datasets/synthetic-data/prompt-status:
    get:
      tags:
      - Datasets
      summary: Get the model configuration stored in the SDG system prompt.
      operationId: get_synthetic_data_prompt_status_api_v2_datasets_synthetic_data_prompt_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyntheticDataPromptStatus'
      security:
      - API Key: []
  /api/v2/datasets/{dataset_id}/versions/{version_number}/generate-synthetic:
    post:
      tags:
      - Datasets
      summary: Generate Synthetic Data
      description: Generate synthetic data rows based on existing dataset patterns.
      operationId: generate_synthetic_data_api_v2_datasets__dataset_id__versions__version_number__generate_synthetic_post
      security:
      - API Key: []
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the dataset.
          title: Dataset Id
        description: ID of the dataset.
      - name: version_number
        in: path
        required: true
        schema:
          type: integer
          description: Version number of the dataset.
          title: Version Number
        description: Version number of the dataset.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyntheticDataGenerationRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyntheticDataGenerationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/datasets/{dataset_id}/versions/{version_number}/generate-synthetic/message:
    post:
      tags:
      - Datasets
      summary: Send Synthetic Data Message
      description: Send a message to refine synthetic data generation.
      operationId: send_synthetic_data_message_api_v2_datasets__dataset_id__versions__version_number__generate_synthetic_message_post
      security:
      - API Key: []
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the dataset.
          title: Dataset Id
        description: ID of the dataset.
      - name: version_number
        in: path
        required: true
        schema:
          type: integer
          description: Version number of the dataset.
          title: Version Number
        description: Version number of the dataset.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyntheticDataConversationRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyntheticDataGenerationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    DatasetResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: ID of the dataset.
        task_id:
          type: string
          title: Task Id
          description: ID of the task the dataset belongs to.
        name:
          type: string
          title: Name
          description: Name of the dataset.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description of the dataset.
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Any metadata to include that describes additional information about the dataset.
        created_at:
          type: integer
          title: Created At
          description: Timestamp representing the time of dataset creation in unix milliseconds.
        updated_at:
          type: integer
          title: Updated At
          description: Timestamp representing the time of the last dataset update in unix milliseconds.
        latest_version_number:
          anyOf:
          - type: integer
          - type: 'null'
          title: Latest Version Number
          description: Version number representing the latest version of the dataset. If unset, no versions exist for the dataset yet.
      type: object
      required:
      - id
      - task_id
      - name
      - created_at
      - updated_at
      title: DatasetResponse
    DatasetVersionRowColumnItemResponse:
      properties:
        column_name:
          type: string
          title: Column Name
          description: Name of the column.
        column_value:
          type: string
          title: Column Value
          description: Value of the column.
      type: object
      required:
      - column_name
      - column_value
      title: DatasetVersionRowColumnItemResponse
    OpenAIMessage-Output:
      properties:
        role:
          $ref: '#/components/schemas/MessageRole'
          description: Role of the message
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: An optional name for the participant. Provides the model information to differentiate between participants of the same role.
        content:
          anyOf:
          - type: string
          - items:
              $ref: '#/components/schemas/OpenAIMessageItem'
            type: array
          - type: 'null'
          title: Content
          description: Content of the message
        tool_calls:
          anyOf:
          - items:
              $ref: '#/components/schemas/ToolCall'
            type: array
          - type: 'null'
          title: Tool Calls
          description: Tool calls made by assistant
        tool_call_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Tool Call Id
          description: ID of the tool call this message is responding to
      type: object
      required:
      - role
      title: OpenAIMessage
      description: 'The message schema class for the prompts playground.

        This class adheres to OpenAI''s message schema.'
    NewDatasetVersionUpdateRowRequest:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: UUID of row to be updated.
        data:
          items:
            $ref: '#/components/schemas/NewDatasetVersionRowColumnItemRequest'
          type: array
          title: Data
          description: List of column-value pairs in the updated row.
      type: object
      required:
      - id
      - data
      title: NewDatasetVersionUpdateRowRequest
      description: Represents a row to be updated in a dataset version.
    ToolCall:
      properties:
        type:
          type: string
          title: Type
          description: The type of tool call. Currently the only type supported is 'function'.
          default: function
        id:
          type: string
          title: Id
          description: Unique identifier for the tool call
        function:
          $ref: '#/components/schemas/ToolCallFunction'
          description: Function details
      type: object
      required:
      - id
      - function
      title: ToolCall
    NewDatasetVersionRowColumnItemRequest:
      properties:
        column_name:
          type: string
          title: Column Name
          description: Name of column.
        column_value:
          type: string
          title: Column Value
          description: Value of column for the row.
      type: object
      required:
      - column_name
      - column_value
      title: NewDatasetVersionRowColumnItemRequest
      description: Represents a single column-value pair in a dataset row.
    SyntheticDataPromptStatus:
      properties:
        model_provider:
          anyOf:
          - $ref: '#/components/schemas/ModelProvider'
          - type: string
            const: empty
          title: Model Provider
          description: Model provider stored in the SDG system prompt. The sentinel 'empty' indicates the prompt has not yet been configured.
        model_name:
          type: string
          title: Model Name
          description: Model name stored in the SDG system prompt
        is_placeholder:
          type: boolean
          title: Is Placeholder
          description: True when the prompt uses the empty placeholder model
      type: object
      required:
      - model_provider
      - model_name
      - is_placeholder
      title: SyntheticDataPromptStatus
    ModelProvider:
      type: string
      enum:
      - anthropic
      - openai
      - gemini
      - bedrock
      - vertex_ai
      - hosted_vllm
      - azure
      title: ModelProvider
    PaginationSortMethod:
      type: string
      enum:
      - asc
      - desc
      title: PaginationSortMethod
    SearchDatasetsResponse:
      properties:
        count:
          type: integer
          title: Count
          description: The total number of datasets matching the parameters.
        datasets:
          items:
            $ref: '#/components/schemas/DatasetResponse'
          type: array
          title: Datasets
          description: List of datasets matching the search filters. Length is less than or equal to page_size parameter
      type: object
      required:
      - count
      - datasets
      title: SearchDatasetsResponse
    NewDatasetVersionRequest:
      properties:
        rows_to_add:
          items:
            $ref: '#/components/schemas/NewDatasetVersionRowRequest'
          type: array
          title: Rows To Add
          description: List of rows to be added to the new dataset version.
        rows_to_delete:
          items:
            type: string
            format: uuid
          type: array
          title: Rows To Delete
          description: List of IDs of rows to be deleted from the new dataset version.
        rows_to_delete_filter:
          anyOf:
          - items:
              $ref: '#/components/schemas/NewDatasetVersionRowColumnItemRequest'
            type: array
          - type: 'null'
          title: Rows To Delete Filter
          description: Optional list of column name and value filters. Rows matching ALL specified column name-value pairs (AND condition) will be deleted from the new dataset version. This filter is applied in addition to rows_to_delete.
        rows_to_update:
          items:
            $ref: '#/components/schemas/NewDatasetVersionUpdateRowRequest'
          type: array
          title: Rows To Update
          description: List of IDs of rows to be updated in the new dataset version with their new values. Should include the value in the row for every column in the dataset, not just the updated column values.
      type: object
      required:
      - rows_to_add
      - rows_to_delete
      - rows_to_update
      title: NewDatasetVersionRequest
    SyntheticDataGenerationRequest:
      properties:
        dataset_purpose:
          type: string
          title: Dataset Purpose
          description: Description of the dataset's purpose and what the data represents.
        column_descriptions:
          items:
            $ref: '#/components/schemas/SyntheticDataColumnDescription'
          type: array
          title: Column Descriptions
          description: Descriptions for each column to guide generation.
        num_rows:
          type: integer
          maximum: 25.0
          minimum: 1.0
          title: Num Rows
          description: Number of rows to generate (1-25).
          default: 10
        model_provider:
          $ref: '#/components/schemas/ModelProvider'
          description: Provider of the LLM model to use for generation.
        model_name:
          type: string
          title: Model Name
          description: Name of the LLM model to use for generation.
        config:
          anyOf:
          - $ref: '#/components/schemas/LLMRequestConfigSettings'
          - type: 'null'
          description: Optional LLM configuration settings (temperature, max_tokens, etc.).
      type: object
      required:
      - dataset_purpose
      - column_descriptions
      - model_provider
      - model_name
      title: SyntheticDataGenerationRequest
      description: Request for initial synthetic data generation.
    DatasetVersionRowResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: ID of the version field.
        data:
          items:
            $ref: '#/components/schemas/DatasetVersionRowColumnItemResponse'
          type: array
          title: Data
          description: List of column names and values in the row.
        created_at:
          type: integer
          title: Created At
          description: Timestamp representing the time of dataset row creation in unix milliseconds. May differ within a version if a row already existed in a past version of the dataset.
      type: object
      required:
      - id
      - data
      - created_at
      title: DatasetVersionRowResponse
    OpenAIMessage-Input:
      properties:
        role:
          $ref: '#/components/schemas/MessageRole'
          description: Role of the message
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: An optional name for the participant. Provides the model information to differentiate between participants of the same role.
        content:
          anyOf:
          - type: string
          - items:
              $ref: '#/components/schemas/OpenAIMessageItem'
            type: array
          - type: 'null'
          title: Content
          description: Content of the message
        tool_calls:
          anyOf:
          - items:
              $ref: '#/components/schemas/ToolCall'
            type: array
          - type: 'null'
          title: Tool Calls
          description: Tool calls made by assistant
        tool_call_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Tool Call Id
          description: ID of the tool call this message is responding to
      type: object
      required:
      - role
      title: OpenAIMessage
      description: 'The message schema class for the prompts playground.

        This class adheres to OpenAI''s message schema.'
    NewDatasetVersionRowRequest:
      properties:
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
          description: Optional ID for the row (used for synthetic data generation).
        data:
          items:
            $ref: '#/components/schemas/NewDatasetVersionRowColumnItemRequest'
          type: array
          title: Data
          description: List of column-value pairs in the new dataset row.
      type: object
      required:
      - data
      title: NewDatasetVersionRowRequest
      description: Represents a row to be added to a dataset version.
    AnthropicThinkingParam-Input:
      properties:
        type:
          type: string
          enum:
          - enabled
          - adaptive
          title: Type
        budget_tokens:
          type: integer
          title: Budget Tokens
      type: object
      title: AnthropicThinkingParam
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SyntheticDataRowResponse:
      properties:
        id:
          type: string
          title: Id
          description: Temporary client-side ID for tracking this row during the session.
        data:
          items:
            $ref: '#/components/schemas/DatasetVersionRowColumnItemResponse'
          type: array
          title: Data
          description: List of column names and values in the generated row.
      type: object
      required:
      - id
      - data
      title: SyntheticDataRowResponse
      description: A single generated row with a temporary client-side ID for tracking.
    DatasetUpdateRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Name of the dataset.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description of the dataset.
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: Any metadata to include that describes additional information about the dataset.
          examples:
          - created_by: John Doe
      type: object
      required:
      - name
      title: DatasetUpdateRequest
    DatasetVersionMetadataResponse:
      properties:
        version_number:
          type: integer
          title: Version Number
          description: Version number of the dataset version.
        created_at:
          type: integer
          title: Created At
          description: Timestamp representing the time of dataset version creation in unix milliseconds.
        dataset_id:
          type: string
          format: uuid
          title: Dataset Id
          description: ID of the dataset.
        column_names:
          items:
            type: string
          type: array
          title: Column Names
          description: Names of all columns in the dataset version.
      type: object
      required:
      - version_number
      - created_at
      - dataset_id
      - column_names
      title: DatasetVersionMetadataResponse
    InputAudio:
      properties:
        data:
          type: string
          title: Data
          description: Base64 encoded audio data
        format:
          type: string
          title: Format
          description: audio format (e.g. 'mp3', 'wav', 'flac', etc.)
      type: object
      required:
      - data
      - format
      title: InputAudio
    SyntheticDataGenerati

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arthurai/refs/heads/main/openapi/arthurai-datasets-api-openapi.yml