ArthurAI Notebooks API

openapi: 3.1.0
info:
  title: Arthur GenAI Engine Agent Discovery Notebooks API
  version: 2.1.688
  description: Endpoints for managing experiment notebooks
tags:
- name: Notebooks
  description: Endpoints for managing experiment notebooks
paths:
  /api/v1/tasks/{task_id}/notebooks:
    post:
      tags:
      - Notebooks
      summary: Create a notebook
      description: Create a new notebook for organizing experiments within a task
      operationId: create_notebook_api_v1_tasks__task_id__notebooks_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/CreateNotebookRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotebookDetail'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Notebooks
      summary: List notebooks
      description: List all notebooks for a task with pagination and optional name search
      operationId: list_notebooks_api_v1_tasks__task_id__notebooks_get
      security:
      - API Key: []
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Task Id
      - name: name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
      - 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/NotebookListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/notebooks/{notebook_id}:
    get:
      tags:
      - Notebooks
      summary: Get notebook details
      description: Get detailed information about a notebook including state and experiment history
      operationId: get_notebook_api_v1_notebooks__notebook_id__get
      security:
      - API Key: []
      parameters:
      - name: notebook_id
        in: path
        required: true
        schema:
          type: string
          description: Notebook ID
          title: Notebook Id
        description: Notebook ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotebookDetail'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Notebooks
      summary: Update notebook metadata
      description: Update notebook name or description (not the state)
      operationId: update_notebook_api_v1_notebooks__notebook_id__put
      security:
      - API Key: []
      parameters:
      - name: notebook_id
        in: path
        required: true
        schema:
          type: string
          description: Notebook ID
          title: Notebook Id
        description: Notebook ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNotebookRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotebookDetail'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Notebooks
      summary: Delete notebook
      description: Delete a notebook (experiments are kept)
      operationId: delete_notebook_api_v1_notebooks__notebook_id__delete
      security:
      - API Key: []
      parameters:
      - name: notebook_id
        in: path
        required: true
        schema:
          type: string
          description: Notebook ID
          title: Notebook Id
        description: Notebook ID
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/notebooks/{notebook_id}/state:
    get:
      tags:
      - Notebooks
      summary: Get notebook state
      description: Get the current state (draft configuration) of a notebook
      operationId: get_notebook_state_api_v1_notebooks__notebook_id__state_get
      security:
      - API Key: []
      parameters:
      - name: notebook_id
        in: path
        required: true
        schema:
          type: string
          description: Notebook ID
          title: Notebook Id
        description: Notebook ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotebookState-Output'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Notebooks
      summary: Set notebook state
      description: Set the state (draft configuration) of a notebook
      operationId: set_notebook_state_api_v1_notebooks__notebook_id__state_put
      security:
      - API Key: []
      parameters:
      - name: notebook_id
        in: path
        required: true
        schema:
          type: string
          description: Notebook ID
          title: Notebook Id
        description: Notebook ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetNotebookStateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotebookDetail'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/notebooks/{notebook_id}/history:
    get:
      tags:
      - Notebooks
      summary: Get notebook history
      description: Get paginated list of experiments run from this notebook
      operationId: get_notebook_history_api_v1_notebooks__notebook_id__history_get
      security:
      - API Key: []
      parameters:
      - name: notebook_id
        in: path
        required: true
        schema:
          type: string
          description: Notebook ID
          title: Notebook Id
        description: Notebook ID
      - 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/PromptExperimentListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    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
    EvalVariableMapping-Input:
      properties:
        variable_name:
          type: string
          title: Variable Name
          description: Name of the eval variable
        source:
          oneOf:
          - $ref: '#/components/schemas/DatasetColumnVariableSource'
          - $ref: '#/components/schemas/ExperimentOutputVariableSource'
          title: Source
          description: Source of the variable value
          discriminator:
            propertyName: type
            mapping:
              dataset_column: '#/components/schemas/DatasetColumnVariableSource'
              experiment_output: '#/components/schemas/ExperimentOutputVariableSource'
      type: object
      required:
      - variable_name
      - source
      title: EvalVariableMapping
      description: Mapping of an eval variable to its source (dataset column or experiment output)
    CreateNotebookRequest:
      properties:
        name:
          type: string
          title: Name
          description: Name of the notebook
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description
        state:
          anyOf:
          - $ref: '#/components/schemas/NotebookState-Input'
          - type: 'null'
          description: Initial state
      type: object
      required:
      - name
      title: CreateNotebookRequest
      description: Request to create a new notebook
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PromptExperimentListResponse:
      properties:
        page:
          type: integer
          title: Page
          description: Current page number (0-indexed)
        page_size:
          type: integer
          title: Page Size
          description: Number of items per page
        total_pages:
          type: integer
          title: Total Pages
          description: Total number of pages
        total_count:
          type: integer
          title: Total Count
          description: Total number of records
        data:
          items:
            $ref: '#/components/schemas/PromptExperimentSummary'
          type: array
          title: Data
          description: List of prompt experiment summaries
      type: object
      required:
      - page
      - page_size
      - total_pages
      - total_count
      - data
      title: PromptExperimentListResponse
      description: Paginated list of prompt experiments
    NotebookListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/NotebookSummary'
          type: array
          title: Data
          description: List of notebook summaries
        page:
          type: integer
          title: Page
          description: Current page number (0-indexed)
        page_size:
          type: integer
          title: Page Size
          description: Number of items per page
        total_pages:
          type: integer
          title: Total Pages
          description: Total number of pages
        total_count:
          type: integer
          title: Total Count
          description: Total number of notebooks
      type: object
      required:
      - data
      - page
      - page_size
      - total_pages
      - total_count
      title: NotebookListResponse
      description: Paginated list of notebooks
    DatasetRef:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Dataset ID
        version:
          type: integer
          title: Version
          description: Dataset version number
        name:
          type: string
          title: Name
          description: Dataset name
      type: object
      required:
      - id
      - version
      - name
      title: DatasetRef
      description: Reference to a dataset and version (with name)
    ModelProvider:
      type: string
      enum:
      - anthropic
      - openai
      - gemini
      - bedrock
      - vertex_ai
      - hosted_vllm
      - azure
      title: ModelProvider
    PaginationSortMethod:
      type: string
      enum:
      - asc
      - desc
      title: PaginationSortMethod
    ExperimentOutputVariableSource:
      properties:
        type:
          type: string
          const: experiment_output
          title: Type
          description: 'Type of source: ''experiment_output'''
        experiment_output:
          $ref: '#/components/schemas/ExperimentOutputSource'
          description: Experiment output source
      type: object
      required:
      - type
      - experiment_output
      title: ExperimentOutputVariableSource
      description: Variable source from experiment output
    PromptVariableMapping-Input:
      properties:
        variable_name:
          type: string
          title: Variable Name
          description: Name of the prompt variable
        source:
          $ref: '#/components/schemas/DatasetColumnVariableSource'
          description: Dataset column source
      type: object
      required:
      - variable_name
      - source
      title: PromptVariableMapping
      description: Mapping of a prompt variable to a dataset column source
    DatasetColumnVariableSource:
      properties:
        type:
          type: string
          const: dataset_column
          title: Type
          description: 'Type of source: ''dataset_column'''
        dataset_column:
          $ref: '#/components/schemas/DatasetColumnSource'
          description: Dataset column source
      type: object
      required:
      - type
      - dataset_column
      title: DatasetColumnVariableSource
      description: Variable source from a dataset column
    NotebookDetail:
      properties:
        id:
          type: string
          title: Id
          description: Notebook ID
        task_id:
          type: string
          title: Task Id
          description: Associated task ID
        name:
          type: string
          title: Name
          description: Notebook name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description
        created_at:
          type: string
          title: Created At
          description: ISO timestamp when created
        updated_at:
          type: string
          title: Updated At
          description: ISO timestamp when last updated
        state:
          $ref: '#/components/schemas/NotebookState-Output'
          description: Current draft state
        experiments:
          items:
            $ref: '#/components/schemas/PromptExperimentSummary'
          type: array
          title: Experiments
          description: History of experiments run from this notebook
      type: object
      required:
      - id
      - task_id
      - name
      - created_at
      - updated_at
      - state
      - experiments
      title: NotebookDetail
      description: Detailed notebook information
    PromptExperimentSummary:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the experiment
        name:
          type: string
          title: Name
          description: Name of the experiment
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description of the experiment
        created_at:
          type: string
          title: Created At
          description: ISO timestamp when experiment was created
        finished_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Finished At
          description: ISO timestamp when experiment finished
        status:
          $ref: '#/components/schemas/ExperimentStatus'
          description: Current status of the experiment
        dataset_id:
          type: string
          format: uuid
          title: Dataset Id
          description: ID of the dataset used
        dataset_name:
          type: string
          title: Dataset Name
          description: Name of the dataset used
        dataset_version:
          type: integer
          title: Dataset Version
          description: Version of the dataset used
        total_rows:
          type: integer
          title: Total Rows
          description: Total number of test rows in the experiment
        completed_rows:
          type: integer
          title: Completed Rows
          description: Number of test rows completed successfully
        failed_rows:
          type: integer
          title: Failed Rows
          description: Number of test rows that failed
        total_cost:
          anyOf:
          - type: string
          - type: 'null'
          title: Total Cost
          description: Total cost of running the experiment
        prompt_configs:
          items:
            oneOf:
            - $ref: '#/components/schemas/SavedPromptConfig'
            - $ref: '#/components/schemas/UnsavedPromptConfig'
            discriminator:
              propertyName: type
              mapping:
                saved: '#/components/schemas/SavedPromptConfig'
                unsaved: '#/components/schemas/UnsavedPromptConfig'
          type: array
          title: Prompt Configs
          description: List of prompts being tested
      type: object
      required:
      - id
      - name
      - created_at
      - status
      - dataset_id
      - dataset_name
      - dataset_version
      - total_rows
      - completed_rows
      - failed_rows
      - prompt_configs
      title: PromptExperimentSummary
      description: Summary of a prompt experiment
    EvalRef-Output:
      properties:
        name:
          type: string
          title: Name
          description: Name of the evaluation
        version:
          type: integer
          title: Version
          description: Version of the evaluation
        variable_mapping:
          items:
            $ref: '#/components/schemas/EvalVariableMapping-Output'
          type: array
          title: Variable Mapping
          description: Mapping of eval variables to data sources
      type: object
      required:
      - name
      - version
      - variable_mapping
      title: EvalRef
      description: Reference to an evaluation configuration
    NotebookState-Input:
      properties:
        prompt_configs:
          anyOf:
          - items:
              oneOf:
              - $ref: '#/components/schemas/SavedPromptConfig'
              - $ref: '#/components/schemas/UnsavedPromptConfig'
              discriminator:
                propertyName: type
                mapping:
                  saved: '#/components/schemas/SavedPromptConfig'
                  unsaved: '#/components/schemas/UnsavedPromptConfig'
            type: array
          - type: 'null'
          title: Prompt Configs
          description: List of prompt configurations
        prompt_variable_mapping:
          anyOf:
          - items:
              $ref: '#/components/schemas/PromptVariableMapping-Input'
            type: array
          - type: 'null'
          title: Prompt Variable Mapping
          description: Variable mappings for prompts
        dataset_ref:
          anyOf:
          - $ref: '#/components/schemas/DatasetRef'
          - type: 'null'
          description: Dataset reference (includes name)
        dataset_row_filter:
          anyOf:
          - items:
              $ref: '#/components/schemas/NewDatasetVersionRowColumnItemRequest'
            type: array
          - type: 'null'
          title: Dataset Row Filter
          description: Optional list of column name and value filters. Only rows matching ALL specified column name-value pairs (AND condition) will be included.
        eval_list:
          anyOf:
          - items:
              $ref: '#/components/schemas/EvalRef-Input'
            type: array
          - type: 'null'
          title: Eval List
          description: List of evaluations
      type: object
      title: NotebookState
      description: Draft state of a notebook - mirrors experiment config but all fields optional.
    NotebookSummary:
      properties:
        id:
          type: string
          title: Id
          description: Notebook ID
        task_id:
          type: string
          title: Task Id
          description: Associated task ID
        name:
          type: string
          title: Name
          description: Notebook name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description
        created_at:
          type: string
          title: Created At
          description: ISO timestamp when created
        updated_at:
          type: string
          title: Updated At
          description: ISO timestamp when last updated
        run_count:
          type: integer
          title: Run Count
          description: Number of experiments run from this notebook
        latest_run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Latest Run Id
          description: ID of most recent experiment run
        latest_run_status:
          anyOf:
          - $ref: '#/components/schemas/ExperimentStatus'
          - type: 'null'
          description: Status of most recent experiment
      type: object
      required:
      - id
      - task_id
      - name
      - created_at
      - updated_at
      - run_count
      title: NotebookSummary
      description: Summary of a notebook
    UnsavedPromptConfig:
      properties:
        type:
          type: string
          const: unsaved
          title: Type
          default: unsaved
        auto_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Auto Name
          description: Auto-generated name (set by backend)
        messages:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Messages
          description: Prompt messages
        model_name:
          type: string
          title: Model Name
          description: LLM model name
        model_provider:
          $ref: '#/components/schemas/ModelProvider'
          description: LLM provider
        tools:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Tools
          description: Available tools
        config:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Config
          description: LLM config settings
        variables:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Variables
          description: Variables (auto-detected if not provided)
      type: object
      required:
      - messages
      - model_name
      - model_provider
      title: UnsavedPromptConfig
      description: Configuration for an unsaved prompt
    EvalVariableMapping-Output:
      properties:
        variable_name:
          type: string
          title: Variable Name
          description: Name of the eval variable
        source:
          oneOf:
          - $ref: '#/components/schemas/DatasetColumnVariableSource'
          - $ref: '#/components/schemas/ExperimentOutputVariableSource'
          title: Source
          description: Source of the variable value
          discriminator:
            propertyName: type
            mapping:
              dataset_column: '#/components/schemas/DatasetColumnVariableSource'
              experiment_output: '#/components/schemas/ExperimentOutputVariableSource'
      type: object
      required:
      - variable_name
      - source
      title: EvalVariableMapping
      description: Mapping of an eval variable to its source (dataset column or experiment output)
    ExperimentStatus:
      type: string
      enum:
      - queued
      - running
      - failed
      - completed
      title: ExperimentStatus
      description: Status of an experiment
    PromptVariableMapping-Output:
      properties:
        variable_name:
          type: string
          title: Variable Name
          description: Name of the prompt variable
        source:
          $ref: '#/components/schemas/DatasetColumnVariableSource'
          description: Dataset column source
      type: object
      required:
      - variable_name
      - source
      title: PromptVariableMapping
      description: Mapping of a prompt variable to a dataset column source
    SavedPromptConfig:
      properties:
        type:
          type: string
          const: saved
          title: Type
          default: saved
        name:
          type: string
          title: Name
          description: Name of the saved prompt
        version:
          type: integer
          title: Version
          description: Version of the saved prompt
      type: object
      required:
      - name
      - version
      title: SavedPromptConfig
      description: Configuration for a saved prompt
    DatasetColumnSource:
      properties:
        name:
          type: string
          title: Name
          description: Name of the dataset column
      type: object
      required:
      - name
      title: DatasetColumnSource
      description: Reference to a dataset column
    SetNotebookStateRequest:
      properties:
        state:
          $ref: '#/components/schemas/NotebookState-Input'
          description: New state for the notebook
      type: object
      required:
      - state
      title: SetNotebookStateRequest
      description: Request to set the notebook state
    UpdateNotebookRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: New name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: New description
      type: object
      title: UpdateNotebookRequest
      description: Request to update a notebook
    NotebookState-Output:
      properties:
        prompt_configs:
          anyOf:
          - items:
              oneOf:
              - $ref: '#/components/schemas/SavedPromptConfig'
              - $ref: '#/components/schemas/UnsavedPromptConfig'
              discriminator:
                propertyName: type
                mapping:
                  saved: '#/components/schemas/SavedPromptConfig'
                  unsaved: '#/components/schemas/UnsavedPromptConfig'
            type: array
          - type: 'null'
          title: Prompt Configs
          description: List of prompt configurations
        prompt_variable_mapping:
          anyOf:
          - items:
              $ref: '#/components/schemas/PromptVariableMapping-Output'
            type: array
          - type: 'null'
          title: Prompt Variable Mapping
          description: Variable mappings for prompts
        dataset_ref:
          anyOf:
          - $ref: '#/components/schemas/DatasetRef'
          - type: 'null'
          description: Dataset reference (includes name)
        dataset_row_filter:
          anyOf:
          - items:
              $ref: '#/components/schemas/NewDatasetVersionRowColumnItemRequest'
            type: array
          - type: 'null'
          title: Dataset Row Filter
          description: Optional list of column name and value filters. Only rows matching ALL specified column name-value pairs (AND condition) will be included.
        eval_list:
          anyOf:
          - items:
              $ref: '#/components/schemas/EvalRef-Output'
            type: array
          - type: 'null'
          title: Eval List
          description: List of evaluations
      type: object
      title: NotebookState
      description: Draft state of a notebook - mirrors experiment config but all fields optional.
    EvalRef-Input:
      properties:
        name:
          type: string
          title: Name
          description: Name of the evaluation
        version:
          type: integer
          title: Version
          description: Version of the evaluation
        variable_mapping:
          items:
            $ref: '#/components/schemas/EvalVariableMapping-Input'
          type: array
          title: Variable Mapping
          description: Mapping of eval variables to data sources
      type: object
      required:
      - name
      - version
      - variable_mapping
      title: EvalRef
      description: Reference to an evaluation configuration
    ExperimentOutputSource:
      properties:
        json_path:
          anyOf:
          - type: string
          - type: 'null'
          title: Json Path
          description: Optional JSON path to extract from experiment output. Should use dot notation for array indexing (eg. response.objects.0.properties.category)
      type: object
      title: ExperimentOutputSource
      description: Reference to experiment output
    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.
  securitySchemes:
    API Key:
      type: http
      description: Bearer token authentication with an API key
      scheme: bearer