Arthur AI Models V1 API

openapi: 3.2.0
info:
  title: Arthur Scope Agents V1 Models V1 API
  version: 0.1.0
servers:
- url: https://platform.arthur.ai/api
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Models V1
paths:
  /api/v1/models/{model_id}:
    patch:
      tags:
      - Models V1
      summary: Update Model
      description: Updates a single model. Requires model_update permission.
      operationId: patch_model
      security:
      - OAuth2AuthorizationCode:
        - model_update
      parameters:
      - name: model_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Model Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchModel'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Models V1
      summary: Get Model By Id
      description: Returns a single model by ID. Requires model_read permission.
      operationId: get_model
      security:
      - OAuth2AuthorizationCode:
        - model_read
      parameters:
      - name: model_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Model Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Models V1
      summary: Delete Model By Id
      description: Deletes a single model. Requires model_delete permission.
      operationId: delete_model
      security:
      - OAuth2AuthorizationCode:
        - model_delete
      parameters:
      - name: model_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Model Id
      responses:
        '204':
          description: No Content
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/models/{model_id}/metric_config:
    put:
      tags:
      - Models V1
      summary: Update Model Metric Configuration By Model Id
      description: Returns a single model metric spec. Requires model_put_metric_config permission.
      operationId: put_model_metric_config
      security:
      - OAuth2AuthorizationCode:
        - model_put_metric_config
      parameters:
      - name: model_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Model Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutModelMetricSpec'
      responses:
        '204':
          description: Successful Response
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/models/{model_id}/schedule:
    put:
      tags:
      - Models V1
      summary: Update Model Metrics Schedule
      description: Creates or overwrites the model metrics job schedule. Requires model_metrics_schedule_update permission.
      operationId: put_model_metrics_schedule
      security:
      - OAuth2AuthorizationCode:
        - model_metrics_schedule_update
      parameters:
      - name: model_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Model Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutModelMetricsSchedule'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Models V1
      summary: Delete Model Metrics Schedule
      description: Deletes metrics job schedule. Requires model_metrics_schedule_delete permission.
      operationId: delete_model_metrics_schedule
      security:
      - OAuth2AuthorizationCode:
        - model_metrics_schedule_delete
      parameters:
      - name: model_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Model Id
      responses:
        '204':
          description: Successful Response
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/workspaces/{workspace_id}/models:
    get:
      tags:
      - Models V1
      summary: Get Workspace Models.
      description: Returns the applications the requesting user has access to across all projects in the workspace, matching the filter and sorting criteria. If multiple filters are specified, results will only be returned that match all of the specified criteria. Requires the workspace_list_models permission (granted by the Workspace Reader role); results are further limited to the projects in which the user has access to models.
      operationId: get_models_in_workspace
      security:
      - OAuth2AuthorizationCode:
        - workspace_list_models
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ModelsSort'
          description: Override the field used for sorting the returned list. Optional.
          default: created_at
        description: Override the field used for sorting the returned list. Optional.
      - name: order
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrder'
          description: Override the sort order used. Optional.
          default: desc
        description: Override the sort order used. Optional.
      - name: dataset_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
          description: Filter for models based on a specific dataset ID.
          title: Dataset Id
        description: Filter for models based on a specific dataset ID.
      - name: name
        in: query
        required: false
        schema:
          type: string
          description: Filter for models with a name similar to this name.
          title: Name
        description: Filter for models with a name similar to this name.
      - name: onboarding_identifier
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter for models whose 'onboarding_identifier' matches the provided string.
          title: Onboarding Identifier
        description: Filter for models whose 'onboarding_identifier' matches the provided string.
      - name: infrastructure
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/Infrastructure'
          - type: 'null'
          description: Filter for models by infrastructure type.
          title: Infrastructure
        description: Filter for models by infrastructure type.
      - name: model_problem_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ModelProblemType'
          - type: 'null'
          description: Filter for models by problem type.
          title: Model Problem Type
        description: Filter for models by problem type.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: The page to return starting from 1 up to total_pages.
          default: 1
          title: Page
        description: The page to return starting from 1 up to total_pages.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: The number of records per page. The max is 1000.
          default: 20
          title: Page Size
        description: The number of records per page. The max is 1000.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList_Model_'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/organization/models:
    get:
      tags:
      - Models V1
      summary: Get Organization Models.
      description: Returns all models (applications) across every workspace in the organization, matching the filter and sorting criteria. If multiple filters are specified, only results matching all criteria are returned. Requires the organization_list_models permission; results are further limited to the projects in which the caller has access to models.
      operationId: get_organization_models
      security:
      - OAuth2AuthorizationCode:
        - organization_list_models
      parameters:
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ModelsSort'
          description: Override the field used for sorting the returned list. Optional.
          default: created_at
        description: Override the field used for sorting the returned list. Optional.
      - name: order
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrder'
          description: Override the sort order used. Optional.
          default: desc
        description: Override the sort order used. Optional.
      - name: dataset_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
          description: Filter for models based on a specific dataset ID.
          title: Dataset Id
        description: Filter for models based on a specific dataset ID.
      - name: name
        in: query
        required: false
        schema:
          type: string
          description: Filter for models with a name similar to this name.
          title: Name
        description: Filter for models with a name similar to this name.
      - name: onboarding_identifier
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter for models whose 'onboarding_identifier' matches the provided string.
          title: Onboarding Identifier
        description: Filter for models whose 'onboarding_identifier' matches the provided string.
      - name: infrastructure
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/Infrastructure'
          - type: 'null'
          description: Filter for models by infrastructure type.
          title: Infrastructure
        description: Filter for models by infrastructure type.
      - name: model_problem_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ModelProblemType'
          - type: 'null'
          description: Filter for models by problem type.
          title: Model Problem Type
        description: Filter for models by problem type.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: The page to return starting from 1 up to total_pages.
          default: 1
          title: Page
        description: The page to return starting from 1 up to total_pages.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: The number of records per page. The max is 1000.
          default: 20
          title: Page Size
        description: The number of records per page. The max is 1000.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList_Model_'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/projects/{project_id}/models:
    post:
      tags:
      - Models V1
      summary: Create Model
      description: Creates a single model. Requires project_create_model permission.
      operationId: post_model
      security:
      - OAuth2AuthorizationCode:
        - project_create_model
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostModel'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Models V1
      summary: List Models
      description: Returns models matching the filter and sorting criteria. If multiple filters are specified, results will only be returned that match all of the specified criteria. Requires project_list_models permission.
      operationId: get_models
      security:
      - OAuth2AuthorizationCode:
        - project_list_models
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ModelsSort'
          description: Override the field used for sorting the returned list. Optional.
          default: created_at
        description: Override the field used for sorting the returned list. Optional.
      - name: order
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrder'
          description: Override the sort order used. Optional.
          default: desc
        description: Override the sort order used. Optional.
      - name: dataset_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
          description: Filter the results for the models that are based on this dataset id. Optional.
          title: Dataset Id
        description: Filter the results for the models that are based on this dataset id. Optional.
      - name: name
        in: query
        required: false
        schema:
          type: string
          description: Filter the results for the models with a name similar to this name. Optional.
          title: Name
        description: Filter the results for the models with a name similar to this name. Optional.
      - name: onboarding_identifier
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter the results for models whose 'onboarding_identifier' matches the provided string.
          title: Onboarding Identifier
        description: Filter the results for models whose 'onboarding_identifier' matches the provided string.
      - name: infrastructure
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/Infrastructure'
          - type: 'null'
          description: Filter for models by infrastructure type.
          title: Infrastructure
        description: Filter for models by infrastructure type.
      - name: model_problem_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ModelProblemType'
          - type: 'null'
          description: Filter for models by problem type.
          title: Model Problem Type
        description: Filter for models by problem type.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: The page to return starting from 1 up to total_pages.
          default: 1
          title: Page
        description: The page to return starting from 1 up to total_pages.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: The number of records per page. The max is 1000.
          default: 20
          title: Page Size
        description: The number of records per page. The max is 1000.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList_Model_'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/projects/{project_id}/generate_metrics_spec:
    post:
      tags:
      - Models V1
      summary: Generates A Metrics Spec.
      description: Generates a metric spec for a model based on one or several datasets. Requires project_generate_metrics_spec permission.
      operationId: generate_metrics_spec
      security:
      - OAuth2AuthorizationCode:
        - project_generate_metrics_spec
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateMetricsSpecRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutModelMetricSpec'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '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
    ModelsSort:
      type: string
      enum:
      - created_at
      - updated_at
      - name
      title: ModelsSort
    UserType:
      type: string
      enum:
      - user
      - data_plane
      - service_account
      title: UserType
    DatasetReference:
      properties:
        dataset_id:
          type: string
          format: uuid
          title: Dataset Id
          description: ID of the dataset.
        dataset_name:
          type: string
          title: Dataset Name
          description: Name of the dataset.
        dataset_connector_type:
          anyOf:
          - $ref: '#/components/schemas/ConnectorType'
          - type: 'null'
          description: Type of connector associated with the dataset. If None, dataset is a joined dataset.
      type: object
      required:
      - dataset_id
      - dataset_name
      - dataset_connector_type
      title: DatasetReference
    DataPlaneCapabilities:
      properties:
        gen_ai_enabled:
          type: boolean
          title: Gen Ai Enabled
          description: Field that records if the engine was installed with GenAI capabilities.
          default: false
      type: object
      title: DataPlaneCapabilities
    AggregationKind:
      type: string
      enum:
      - default
      - custom
      title: AggregationKind
    GenerateMetricsSpecRequest:
      properties:
        dataset_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Dataset Ids
          description: List of dataset IDs for which to generate a model metrics spec. Datasets must be in the project in the path.
      type: object
      required:
      - dataset_ids
      title: GenerateMetricsSpecRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PostModel:
      properties:
        name:
          type: string
          title: Name
          description: Name of the model.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description of model.
        onboarding_identifier:
          anyOf:
          - type: string
            maxLength: 1024
          - type: 'null'
          title: Onboarding Identifier
          description: An optional label to help identify the model. Used by the task creation onboarding flow.
        metric_config:
          anyOf:
          - $ref: '#/components/schemas/PutModelMetricSpec'
          - type: 'null'
          description: Metric configuration of the model. If left undefined, one will be derived
        dataset_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Dataset Ids
          description: IDs of datasets for the model.
      type: object
      required:
      - name
      - dataset_ids
      title: PostModel
    ModelProblemType:
      type: string
      enum:
      - regression
      - binary_classification
      - arthur_shield
      - custom
      - multiclass_classification
      - agentic_trace
      title: ModelProblemType
    ModelMetricSpec:
      properties:
        aggregation_specs:
          items:
            $ref: '#/components/schemas/AggregationSpec'
          type: array
          title: Aggregation Specs
          description: List of aggregations configured for the metric spec.
        id:
          type: string
          format: uuid
          title: Id
          description: Unique ID of the metric spec.
      type: object
      required:
      - aggregation_specs
      - id
      title: ModelMetricSpec
    PutModelMetricSpec:
      properties:
        aggregation_specs:
          items:
            $ref: '#/components/schemas/AggregationSpec'
          type: array
          title: Aggregation Specs
          description: List of aggregations configured for the metric spec.
      type: object
      required:
      - aggregation_specs
      title: PutModelMetricSpec
    Pagination:
      properties:
        page:
          type: integer
          title: Page
          description: The current page number. Page 1 is the first page.
          default: 1
        page_size:
          type: integer
          title: Page Size
          description: Number of records per page.
          default: 20
        total_pages:
          type: integer
          title: Total Pages
          description: Total number of pages.
        total_records:
          type: integer
          title: Total Records
          description: Total number of records across all pages.
      type: object
      required:
      - total_pages
      - total_records
      title: Pagination
    PutModelMetricsSchedule:
      properties:
        cron:
          type: string
          title: Cron
          description: Cron expression defining a cadence to run the model's metrics job on. Must specify a period greater than or equal to 5 minutes.
        lookback_period_seconds:
          type: integer
          title: Lookback Period Seconds
          description: Lookback period of the scheduled job.
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Optional name of the schedule.
      type: object
      required:
      - cron
      - lookback_period_seconds
      title: PutModelMetricsSchedule
    NotFoundError:
      properties:
        detail:
          type: string
          title: Detail
          default: Resource not found
      type: object
      title: NotFoundError
    BadRequestError:
      properties:
        detail:
          type: string
          title: Detail
          default: Bad Request
      type: object
      title: BadRequestError
    Model:
      properties:
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Time of record creation.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Time of last record update.
        id:
          type: string
          format: uuid
          title: Id
          description: ID of the model.
        project_id:
          type: string
          format: uuid
          title: Project Id
          description: ID of the parent project.
        name:
          type: string
          title: Name
          description: Name of the model.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Description of model.
        onboarding_identifier:
          anyOf:
          - type: string
          - type: 'null'
          title: Onboarding Identifier
          description: An optional label to help identify the model. Used by the task creation onboarding flow.
        last_updated_by_user:
          anyOf:
          - $ref: '#/components/schemas/User'
          - type: 'null'
          description: Information for user who last updated the connector.
        metric_config:
          $ref: '#/components/schemas/ModelMetricSpec'
          description: Metric configuration of the model.
        schedule:
          anyOf:
          - $ref: '#/components/schemas/ModelMetricsSchedule'
          - type: 'null'
          description: Schedule used to automatically enqueue jobs.
        model_problem_types:
          items:
            $ref: '#/components/schemas/ModelProblemType'
          type: array
          title: Model Problem Types
          description: Unique model problem types of associated datasets.
        datasets:
          items:
            $ref: '#/components/schemas/DatasetReference'
          type: array
          title: Datasets
          description: Datasets for the model.
        data_plane_id:
          type: string
          format: uuid
          title: Data Plane

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arthur-ai/refs/heads/main/openapi/arthur-ai-models-v1-api-openapi.yml