Microsoft Azure HyperDriveExperiment API

openapi: 3.2.0
info:
  description: HyperDrive REST API
  version: '2019-09-30'
  title: Microsoft Azure HyperDrive Hyper Drive Experiment API
security:
- azure_auth:
  - user_impersonation
tags:
- name: HyperDriveExperiment
paths:
  /hyperdrive/v1.0/{armScope}/runs:
    post:
      tags:
      - HyperDriveExperiment
      summary: Microsoft Azure Create An Experiment
      description: Create a HyperDrive Experiment.
      operationId: microsoftAzureHyperparametertuningCreateexperiment
      parameters:
      - $ref: '#/components/parameters/ArmScopeParameter'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HyperDriveExperimentResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HyperDriveErrorResponse'
      x-ms-examples:
        Create a HyperDrive experiment:
          $ref: ./examples/createHyperDriveExperiment.json
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                config:
                  type: string
                  description: The configuration file with experiment JSON content. A text file that is a JSON-serialized '#/definitions/HyperDriveCreateExperiment' object.
                  format: binary
              required:
              - config
  /hyperdrive/v1.0/{armScope}/runs/{runId}/cancel:
    post:
      tags:
      - HyperDriveExperiment
      summary: Microsoft Azure Cancel An Experiment
      description: Cancel a HyperDrive Experiment.
      operationId: microsoftAzureHyperparametertuningCancelexperiment
      parameters:
      - $ref: '#/components/parameters/ArmScopeParameter'
      - name: runId
        in: path
        description: Hyperdrive run id to cancel.
        required: true
        schema:
          type: string
      - in: header
        name: RunHistoryHost
        description: The host for run location.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HyperDriveCancelExperimentResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HyperDriveErrorResponse'
      x-ms-examples:
        Cancel a HyperDrive experiment:
          $ref: ./examples/cancelHyperDriveExperiment.json
components:
  schemas:
    HyperDriveExperimentResponse:
      description: Response for HyperDrive_CreateExperiment in case of success.
      properties:
        code:
          format: int32
          type: integer
          description: Response code.
        result:
          description: Details about created Hyperdrive run.
          $ref: '#/components/schemas/HyperDriveExperiment'
      required:
      - code
      - result
      type: object
    HyperDriveCancelExperimentResponse:
      properties:
        code:
          format: int32
          type: integer
          description: Response code.
        result:
          type: string
          description: Message indicating operation success.
      required:
      - code
      - result
      type: object
      description: Response for HyperDrive_CancelExperiment in case of success.
    HyperDriveExperimentBase:
      description: Base object for both request and response of HyperDrive_CreateExperiment api.
      properties:
        description:
          maxLength: 511
          type:
          - string
          - 'null'
          description: The description for Hyperdrive run.
        generator_config:
          description: Hyperparameter space and the sampling method configuration.
          properties:
            name:
              type: string
              enum:
              - RANDOM
              - GRID
              - BAYESIANOPTIMIZATION
              description: Hyperparameter sampling method.
              x-ms-enum:
                name: Name
                modelAsString: true
            parameter_space:
              type: object
              additionalProperties:
                type: array
                items: {}
                minItems: 2
                maxItems: 2
                description: "The first element in the array is a string identifying the parameter expression type like choice, uniform etc. The second element is a parameter expressions corresponding to the type.\n Please refer to https://docs.microsoft.com/en-us/python/api/azureml-train-core/azureml.train.hyperdrive.parameter_expressions?view=azure-ml-py for a list of supported types and options for each type.\n choice parameters are specified as ['choice', [[1, 2, 3, 4]]]. randint is in format ['randint', [1]].\n uniform, loguniform, normal, lognormal are in format [expression type, [0.01, 0.05]].\n quniform, qloguniform, qnormal, qlognormal are in format [expression type, [0.01, 0.05, 3]].\n"
                example:
                - choice
                - - - 1
                    - 2
                    - 3
                    - 4
              description: Dictionary specifying hyperparameter space.
          required:
          - name
          - parameter_space
          type: object
        max_concurrent_jobs:
          format: int32
          maximum: 100
          minimum: 1
          type: integer
          description: Maximum number of runs to run concurrently.
        max_duration_minutes:
          format: int32
          maximum: 43200
          minimum: 1
          type: integer
          description: Maximum duration of the Hyperdrive run.
        max_total_jobs:
          format: int32
          maximum: 1000
          minimum: 1
          type: integer
          description: Maximum number of runs.
        name:
          maxLength: 255
          type: string
          description: Name of the Hyperdrive run.
        platform:
          type: string
          enum:
          - AML
          description: Platform of the Hyperdrive run.
          x-ms-enum:
            name: Platform
            modelAsString: true
        platform_config:
          type: object
          description: Platform config object specifying the run definition structure.
        policy_config:
          description: Early termination policy configuration.
          $ref: '#/components/schemas/HyperDrivePolicyConfigBase'
        primary_metric_config:
          description: Name of the primary metric and goal of optimizing.
          properties:
            goal:
              type: string
              enum:
              - MAXIMIZE
              - MINIMIZE
              description: Determines if the primary metric has to be minimized/maximized.
              x-ms-enum:
                name: Goal
                modelAsString: true
            name:
              type: string
              description: Name of the primary metric reported by runs.
          required:
          - goal
          - name
          type: object
        study_id:
          format: int32
          minimum: 0
          type:
          - integer
          - 'null'
          description: Study Id of the Hyperdrive run.
      required:
      - generator_config
      - name
      - platform
      - platform_config
      - policy_config
      - primary_metric_config
      type: object
    HyperDriveErrorResponse:
      properties:
        code:
          format: int32
          type: integer
          description: Error response code.
        message:
          type: string
          description: Error message.
      required:
      - code
      - message
      type: object
      description: Response in case of an error.
    HyperDrivePolicyConfigBase:
      description: Early termination policy configuration.
      properties:
        name:
          type: string
          enum:
          - Default
          - Bandit
          - MedianStopping
          - TruncationSelection
          description: Type of early termination policy.
          x-ms-enum:
            name: Name
            modelAsString: true
      required:
      - name
      type: object
      discriminator:
        propertyName: name
    HyperDriveExperiment:
      type: object
      description: Part of response for HyperDrive_CreateExperiment in case of success. Contains details about the created hyperdrive run.
      allOf:
      - $ref: '#/components/schemas/HyperDriveExperimentBase'
      - type: object
        properties:
          all_jobs_generated:
            type: boolean
            description: Indicates if all runs have been generated.
          cancellation_requested:
            type: boolean
            description: Indicates if cancellation has been requested for this Hyperdrive run.
          created:
            format: date-time
            type: string
            description: Hyperdrive run creation time.
          created_by_user_id:
            format: int32
            type: integer
            description: Id of the user who created the Hyperdrive run.
          experiment_id:
            type: string
            description: Hyperdrive run id.
          experiment_uri:
            type: string
            description: Hyperdrive run Uri.
          modified:
            format: date-time
            type: string
            description: Hyperdrive run modification time.
          status:
            type: string
            description: Hyperdrive run status.
          study_uri:
            type: string
            description: Study Uri of the Hyperdrive run.
          hyperdrive_run_id:
            type: string
            description: Hyperdrive run id.
        required:
        - all_jobs_generated
        - cancellation_requested
        - created
        - created_by_user_id
        - experiment_id
        - modified
        - status
        - hyperdrive_run_id
      properties: {}
  parameters:
    ArmScopeParameter:
      name: armScope
      in: path
      description: "The ARM scope passed in through URL with format:\n            subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.MachineLearningServices/workspaces/{workspaceName}/experiments/{experimentName}.\n"
      required: true
      x-ms-skip-url-encoding: true
      x-ms-parameter-location: method
      schema:
        type: string
  securitySchemes:
    azure_auth:
      type: oauth2
      flows:
        implicit:
          scopes:
            user_impersonation: impersonate your user account
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize