ArthurAI Agentic Notebooks API
The Agentic Notebooks API from ArthurAI — 4 operation(s) for agentic notebooks.
The Agentic Notebooks API from ArthurAI — 4 operation(s) for agentic notebooks.
openapi: 3.1.0
info:
title: Arthur GenAI Engine Agent Discovery Agentic Notebooks API
version: 2.1.688
tags:
- name: Agentic Notebooks
paths:
/api/v1/tasks/{task_id}/agentic_notebooks:
post:
tags:
- Agentic Notebooks
summary: Create an agentic notebook
description: Create a new agentic notebook for organizing experiments within a task
operationId: create_agentic_notebook_api_v1_tasks__task_id__agentic_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/CreateAgenticNotebookRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AgenticNotebookDetail'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Agentic Notebooks
summary: List agentic notebooks
description: List all agentic notebooks for a task with pagination and optional name search
operationId: list_agentic_notebooks_api_v1_tasks__task_id__agentic_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/AgenticNotebookListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/agentic_notebooks/{notebook_id}:
get:
tags:
- Agentic Notebooks
summary: Get agentic notebook details
description: Get detailed information about an agentic notebook including state and experiment history
operationId: get_agentic_notebook_api_v1_agentic_notebooks__notebook_id__get
security:
- API Key: []
parameters:
- name: notebook_id
in: path
required: true
schema:
type: string
description: Agentic Notebook ID
title: Notebook Id
description: Agentic Notebook ID
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AgenticNotebookDetail'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- Agentic Notebooks
summary: Update agentic notebook metadata
description: Update agentic notebook name or description (not the state)
operationId: update_agentic_notebook_api_v1_agentic_notebooks__notebook_id__put
security:
- API Key: []
parameters:
- name: notebook_id
in: path
required: true
schema:
type: string
description: Agentic Notebook ID
title: Notebook Id
description: Agentic Notebook ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAgenticNotebookRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AgenticNotebookDetail'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Agentic Notebooks
summary: Delete agentic notebook
description: Delete an agentic notebook (experiments are kept)
operationId: delete_agentic_notebook_api_v1_agentic_notebooks__notebook_id__delete
security:
- API Key: []
parameters:
- name: notebook_id
in: path
required: true
schema:
type: string
description: Agentic Notebook ID
title: Notebook Id
description: Agentic Notebook ID
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/agentic_notebooks/{notebook_id}/state:
get:
tags:
- Agentic Notebooks
summary: Get agentic notebook state
description: Get the current state (draft configuration) of an agentic notebook
operationId: get_agentic_notebook_state_api_v1_agentic_notebooks__notebook_id__state_get
security:
- API Key: []
parameters:
- name: notebook_id
in: path
required: true
schema:
type: string
description: Agentic Notebook ID
title: Notebook Id
description: Agentic Notebook ID
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AgenticNotebookStateResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- Agentic Notebooks
summary: Set agentic notebook state
description: Set the state (draft configuration) of an agentic notebook
operationId: set_agentic_notebook_state_api_v1_agentic_notebooks__notebook_id__state_put
security:
- API Key: []
parameters:
- name: notebook_id
in: path
required: true
schema:
type: string
description: Agentic Notebook ID
title: Notebook Id
description: Agentic Notebook ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SetAgenticNotebookStateRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AgenticNotebookDetail'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/agentic_notebooks/{notebook_id}/history:
get:
tags:
- Agentic Notebooks
summary: Get agentic notebook history
description: Get paginated list of experiments run from this agentic notebook
operationId: get_agentic_notebook_history_api_v1_agentic_notebooks__notebook_id__history_get
security:
- API Key: []
parameters:
- name: notebook_id
in: path
required: true
schema:
type: string
description: Agentic Notebook ID
title: Notebook Id
description: Agentic 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/AgenticExperimentListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
AgenticExperimentListResponse:
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/AgenticExperimentSummary'
type: array
title: Data
description: List of agentic experiment summaries
type: object
required:
- page
- page_size
- total_pages
- total_count
- data
title: AgenticExperimentListResponse
description: Paginated list of agentic experiments
AgenticEvalVariableMapping-Output:
properties:
variable_name:
type: string
title: Variable Name
description: Name of the eval variable
source:
oneOf:
- $ref: '#/components/schemas/DatasetColumnVariableSource'
- $ref: '#/components/schemas/AgenticExperimentOutputVariableSource'
title: Source
description: Source of the variable value
discriminator:
propertyName: type
mapping:
dataset_column: '#/components/schemas/DatasetColumnVariableSource'
experiment_output: '#/components/schemas/AgenticExperimentOutputVariableSource'
type: object
required:
- variable_name
- source
title: AgenticEvalVariableMapping
description: 'Mapping of an eval variable to its source (dataset column or experiment output).
For transform variables, use ExperimentOutputVariableSource with transform_variable_name
in the experiment_output field. The transform_id comes from the associated AgenticEvalRef.'
RequestTimeParameterSource:
properties:
type:
type: string
const: request_time_parameter
title: Type
description: 'Type of source: ''request_time_parameter'''
type: object
required:
- type
title: RequestTimeParameterSource
description: Variable source from request-time parameters (e.g., tokens, API keys)
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
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
GeneratedVariableSource:
properties:
type:
type: string
const: generated
title: Type
description: 'Type of source: ''generated'''
generator_type:
$ref: '#/components/schemas/AgenticExperimentGeneratorType'
description: 'Type of generator to use. Supported values: ''uuid'', ''session_id''. Exactly one session_id is required per experiment.'
type: object
required:
- type
- generator_type
title: GeneratedVariableSource
description: Variable source for generated values (e.g., UUIDs, timestamps)
SetAgenticNotebookStateRequest:
properties:
state:
$ref: '#/components/schemas/AgenticNotebookState'
description: New state for the notebook
type: object
required:
- state
title: SetAgenticNotebookStateRequest
description: Request to set the agentic notebook state
AgenticEvalRef-Input:
properties:
name:
type: string
title: Name
description: Name of the evaluation
version:
type: integer
title: Version
description: Version of the evaluation
transform_id:
type: string
format: uuid
title: Transform Id
description: ID of the transform to apply to the trace before evaluation
variable_mapping:
items:
$ref: '#/components/schemas/AgenticEvalVariableMapping-Input'
type: array
title: Variable Mapping
description: Mapping of eval variables to data sources (supports transform variables for agentic experiments)
type: object
required:
- name
- version
- transform_id
- variable_mapping
title: AgenticEvalRef
description: Reference to an evaluation configuration with transform
AgenticNotebookState:
properties:
http_template:
anyOf:
- $ref: '#/components/schemas/HttpTemplate'
- type: 'null'
description: HTTP template configuration for the agent endpoint
template_variable_mapping:
anyOf:
- items:
$ref: '#/components/schemas/TemplateVariableMapping-Input'
type: array
- type: 'null'
title: Template Variable Mapping
description: Mapping of template variables to their sources (dataset columns, request-time parameters, or generated variables like UUIDs)
dataset_ref:
anyOf:
- $ref: '#/components/schemas/DatasetRefInput'
- 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/AgenticEvalRef-Input'
type: array
- type: 'null'
title: Eval List
description: List of evaluations
type: object
title: AgenticNotebookState
description: 'Draft state of an agentic notebook - mirrors agentic experiment config but all fields optional.
Used for requests (input).'
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)
CreateAgenticNotebookRequest:
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/AgenticNotebookState'
- type: 'null'
description: Initial state
type: object
required:
- name
title: CreateAgenticNotebookRequest
description: Request to create a new agentic notebook
AgenticEvalRef-Output:
properties:
name:
type: string
title: Name
description: Name of the evaluation
version:
type: integer
title: Version
description: Version of the evaluation
transform_id:
type: string
format: uuid
title: Transform Id
description: ID of the transform to apply to the trace before evaluation
variable_mapping:
items:
$ref: '#/components/schemas/AgenticEvalVariableMapping-Output'
type: array
title: Variable Mapping
description: Mapping of eval variables to data sources (supports transform variables for agentic experiments)
type: object
required:
- name
- version
- transform_id
- variable_mapping
title: AgenticEvalRef
description: Reference to an evaluation configuration with transform
UpdateAgenticNotebookRequest:
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: UpdateAgenticNotebookRequest
description: Request to update an agentic notebook
DatasetRefInput:
properties:
id:
type: string
format: uuid
title: Id
description: Dataset ID
version:
type: integer
title: Version
description: Dataset version number
type: object
required:
- id
- version
title: DatasetRefInput
description: Reference to a dataset and version for input (without name)
AgenticExperimentOutputVariableSource:
properties:
type:
type: string
const: experiment_output
title: Type
description: 'Type of source: ''experiment_output'''
experiment_output:
$ref: '#/components/schemas/TransformVariableExperimentOutputSource'
description: Experiment output source (only transform variables supported)
type: object
required:
- type
- experiment_output
title: AgenticExperimentOutputVariableSource
description: Variable source from experiment output (agentic experiments only support transform variables)
PaginationSortMethod:
type: string
enum:
- asc
- desc
title: PaginationSortMethod
AgenticNotebookDetail:
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/AgenticNotebookStateResponse'
description: Current draft state
experiments:
items:
$ref: '#/components/schemas/AgenticExperimentSummary'
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: AgenticNotebookDetail
description: Detailed agentic notebook information
TransformVariableExperimentOutputSource:
properties:
type:
type: string
const: transform_variable
title: Type
description: Type of experiment output source
default: transform_variable
transform_variable_name:
type: string
title: Transform Variable Name
description: Name of the variable to extract from the transform. The transform_id comes from the eval configuration.
type: object
required:
- transform_variable_name
title: TransformVariableExperimentOutputSource
description: Reference to experiment output using transform variable extraction (agentic experiments only)
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
AgenticNotebookStateResponse:
properties:
http_template:
anyOf:
- $ref: '#/components/schemas/HttpTemplate'
- type: 'null'
description: HTTP template configuration for the agent endpoint
template_variable_mapping:
anyOf:
- items:
$ref: '#/components/schemas/TemplateVariableMapping-Output'
type: array
- type: 'null'
title: Template Variable Mapping
description: Mapping of template variables to their sources (dataset columns, request-time parameters, or generated variables like UUIDs)
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/AgenticEvalRef-Output'
type: array
- type: 'null'
title: Eval List
description: List of evaluations
type: object
title: AgenticNotebookStateResponse
description: 'Draft state of an agentic notebook - mirrors agentic experiment config but all fields optional.
Used for responses (output).'
AgenticExperimentSummary:
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
http_template:
$ref: '#/components/schemas/HttpTemplate'
description: HTTP template configuration for the agent endpoint
type: object
required:
- id
- name
- created_at
- status
- dataset_id
- dataset_name
- dataset_version
- total_rows
- completed_rows
- failed_rows
- http_template
title: AgenticExperimentSummary
description: Summary of an agentic experiment
ExperimentStatus:
type: string
enum:
- queued
- running
- failed
- completed
title: ExperimentStatus
description: Status of an experiment
TemplateVariableMapping-Output:
properties:
variable_name:
type: string
title: Variable Name
description: Name of the template variable
source:
oneOf:
- $ref: '#/components/schemas/DatasetColumnVariableSource'
- $ref: '#/components/schemas/RequestTimeParameterSource'
- $ref: '#/components/schemas/GeneratedVariableSource'
title: Source
description: Source of the variable value
discriminator:
propertyName: type
mapping:
dataset_column: '#/components/schemas/DatasetColumnVariableSource'
generated: '#/components/schemas/GeneratedVariableSource'
request_time_parameter: '#/components/schemas/RequestTimeParameterSource'
type: object
required:
- variable_name
- source
title: TemplateVariableMapping
description: Mapping of a template variable to its source
TemplateVariableMapping-Input:
properties:
variable_name:
type: string
title: Variable Name
description: Name of the template variable
source:
oneOf:
- $ref: '#/components/schemas/DatasetColumnVariableSource'
- $ref: '#/components/schemas/RequestTimeParameterSource'
- $ref: '#/components/schemas/GeneratedVariableSource'
title: Source
description: Source of the variable value
discriminator:
propertyName: type
mapping:
dataset_column: '#/components/schemas/DatasetColumnVariableSource'
generated: '#/components/schemas/GeneratedVariableSource'
request_time_parameter: '#/components/schemas/RequestTimeParameterSource'
type: object
required:
- variable_name
- source
title: TemplateVariableMapping
description: Mapping of a template variable to its source
AgenticEvalVariableMapping-Input:
properties:
variable_name:
type: string
title: Variable Name
description: Name of the eval variable
source:
oneOf:
- $ref: '#/components/schemas/DatasetColumnVariableSource'
- $ref: '#/components/schemas/AgenticExperimentOutputVariableSource'
title: Source
description: Source of the variable value
discriminator:
propertyName: type
mapping:
dataset_column: '#/components/schemas/DatasetColumnVariableSource'
experiment_output: '#/components/schemas/AgenticExperimentOutputVariableSource'
type: object
required:
- variable_name
- source
title: AgenticEvalVariableMapping
description: 'Mapping of an eval variable to its source (dataset column or experiment output).
For transform variables, use ExperimentOutputVariableSource with transform_variable_name
in the experiment_output field. The transform_id comes from the associated AgenticEvalRef.'
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
HttpHeader:
properties:
name:
type: string
title: Name
description: Header name (supports {{variable}} placeholders)
value:
type: string
title: Value
description: Header value (supports {{variable}} placeholders)
type: object
required:
- name
- value
title: HttpHeader
description: HTTP header with support for variable placeholders
AgenticNotebookListResponse:
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/AgenticNotebookSummary'
type: array
title: Data
description: List of notebook summaries
type: object
required:
- page
- page_size
- total_pages
- total_count
- data
title: AgenticNotebookListResponse
description: Paginated list of agentic notebooks
AgenticNotebookSummary:
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 no
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arthurai/refs/heads/main/openapi/arthurai-agentic-notebooks-api-openapi.yml