{
  "swagger": "2.0",
  "info": {
    "description": "HyperDrive REST API",
    "version": "2019-09-30",
    "title": "HyperDrive"
  },
  "tags": [],
  "schemes": [
    "https"
  ],
  "paths": {
    "/hyperdrive/v1.0/{armScope}/runs": {
      "post": {
        "tags": [
          "HyperDriveExperiment"
        ],
        "summary": "Create an Experiment.",
        "description": "Create a HyperDrive Experiment.",
        "operationId": "HyperparameterTuning_CreateExperiment",
        "consumes": [
          "multipart/form-data"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "$ref": "#/parameters/ArmScopeParameter"
          },
          {
            "in": "formData",
            "name": "config",
            "description": "The configuration file with experiment JSON content. A text file that is a JSON-serialized '#/definitions/HyperDriveCreateExperiment' object.",
            "type": "file",
            "required": true
          }
        ],
        "responses": {
          "201": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/HyperDriveExperimentResponse"
            }
          },
          "default": {
            "description": "Error",
            "schema": {
              "$ref": "#/definitions/HyperDriveErrorResponse"
            }
          }
        },
        "x-ms-examples": {
          "Create a HyperDrive experiment": {
            "$ref": "./examples/createHyperDriveExperiment.json"
          }
        }
      }
    },
    "/hyperdrive/v1.0/{armScope}/runs/{runId}/cancel": {
      "post": {
        "tags": [
          "HyperDriveExperiment"
        ],
        "summary": "Cancel an Experiment.",
        "description": "Cancel a HyperDrive Experiment.",
        "operationId": "HyperparameterTuning_CancelExperiment",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "$ref": "#/parameters/ArmScopeParameter"
          },
          {
            "name": "runId",
            "in": "path",
            "description": "Hyperdrive run id to cancel.",
            "required": true,
            "type": "string"
          },
          {
            "in": "header",
            "name": "RunHistoryHost",
            "description": "The host for run location.",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/HyperDriveCancelExperimentResponse"
            }
          },
          "default": {
            "description": "Error",
            "schema": {
              "$ref": "#/definitions/HyperDriveErrorResponse"
            }
          }
        },
        "x-ms-examples": {
          "Cancel a HyperDrive experiment": {
            "$ref": "./examples/cancelHyperDriveExperiment.json"
          }
        }
      }
    }
  },
  "definitions": {
    "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."
    },
    "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",
          "x-nullable": true,
          "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.\r\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.\r\n choice parameters are specified as ['choice', [[1, 2, 3, 4]]]. randint is in format ['randint', [1]].\r\n uniform, loguniform, normal, lognormal are in format [expression type, [0.01, 0.05]].\r\n quniform, qloguniform, qnormal, qlognormal are in format [expression type, [0.01, 0.05, 3]].\r\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": "#/definitions/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",
          "x-nullable": true,
          "description": "Study Id of the Hyperdrive run."
        }
      },
      "required": [
        "generator_config",
        "name",
        "platform",
        "platform_config",
        "policy_config",
        "primary_metric_config"
      ],
      "type": "object"
    },
    "HyperDriveExperiment": {
      "type": "object",
      "description": "Part of response for HyperDrive_CreateExperiment in case of success. Contains details about the created hyperdrive run.",
      "allOf": [
        {
          "$ref": "#/definitions/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": {}
    },
    "HyperDriveCreateExperiment": {
      "type": "object",
      "description": "Part of request for HyperDrive_CreateExperiment. Contains configuration details required to create hyperdrive run.",
      "allOf": [
        {
          "$ref": "#/definitions/HyperDriveExperimentBase"
        },
        {
          "type": "object",
          "properties": {
            "user": {
              "maxLength": 255,
              "type": "string",
              "description": "User who is creating the Hyperdrive run."
            }
          },
          "required": [
            "user"
          ]
        }
      ],
      "properties": {}
    },
    "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": "name"
    },
    "HyperDriveDefaultPolicy": {
      "type": "object",
      "description": "No early termination is applied in the case of DefaultPolicy",
      "allOf": [
        {
          "$ref": "#/definitions/HyperDrivePolicyConfigBase"
        }
      ],
      "properties": {},
      "x-ms-discriminator-value": "Default"
    },
    "HyperDriveBanditPolicy": {
      "type": "object",
      "description": "Bandit Policy configuration. Please refer https://docs.microsoft.com/en-us/python/api/azureml-train-core/azureml.train.hyperdrive.banditpolicy?view=azure-ml-py for more information.",
      "allOf": [
        {
          "$ref": "#/definitions/HyperDrivePolicyConfigBase"
        },
        {
          "type": "object",
          "properties": {
            "properties": {
              "type": "object",
              "description": "Policy configuration properties.",
              "properties": {
                "evaluation_interval": {
                  "format": "int32",
                  "type": "integer",
                  "description": "Evaluation interval of the policy."
                },
                "delay_evaluation": {
                  "format": "int32",
                  "type": "integer",
                  "description": "Value indicating the number of sequences for which the first evaluation is delayed."
                },
                "slack_factor": {
                  "format": "float",
                  "type": "number",
                  "description": "Slack factor."
                },
                "slack_amount": {
                  "format": "float",
                  "type": "number",
                  "description": "Slack amount."
                }
              }
            }
          }
        }
      ],
      "properties": {},
      "x-ms-discriminator-value": "Bandit"
    },
    "HyperDriveMedianStoppingPolicy": {
      "type": "object",
      "description": "Median stopping policy configuration. Please refer https://docs.microsoft.com/en-us/python/api/azureml-train-core/azureml.train.hyperdrive.medianstoppingpolicy?view=azure-ml-py for more information.",
      "allOf": [
        {
          "$ref": "#/definitions/HyperDrivePolicyConfigBase"
        },
        {
          "type": "object",
          "properties": {
            "properties": {
              "type": "object",
              "description": "Policy configuration properties.",
              "properties": {
                "evaluation_interval": {
                  "format": "int32",
                  "type": "integer",
                  "description": "Evaluation interval of the policy."
                },
                "delay_evaluation": {
                  "format": "int32",
                  "type": "integer",
                  "description": "Value indicating the number of sequences for which the first evaluation is delayed."
                }
              }
            }
          }
        }
      ],
      "properties": {},
      "x-ms-discriminator-value": "MedianStopping"
    },
    "HyperDriveTruncationSelectionPolicy": {
      "type": "object",
      "description": "Truncation selection policy configuration. Please refer https://docs.microsoft.com/en-us/python/api/azureml-train-core/azureml.train.hyperdrive.truncationselectionpolicy?view=azure-ml-py for more information.",
      "allOf": [
        {
          "$ref": "#/definitions/HyperDrivePolicyConfigBase"
        },
        {
          "type": "object",
          "properties": {
            "properties": {
              "type": "object",
              "description": "Policy configuration properties.",
              "properties": {
                "evaluation_interval": {
                  "format": "int32",
                  "type": "integer",
                  "description": "Evaluation interval of the policy."
                },
                "delay_evaluation": {
                  "format": "int32",
                  "type": "integer",
                  "description": "Value indicating the number of sequences for which the first evaluation is delayed."
                },
                "truncation_percentage": {
                  "format": "int32",
                  "type": "integer",
                  "description": "Truncation percentage value."
                },
                "exclude_finished_jobs": {
                  "type": "boolean",
                  "description": "Boolean indicating if metrics from finished jobs should be excluded in the policy decision process."
                }
              }
            }
          }
        }
      ],
      "properties": {},
      "x-ms-discriminator-value": "TruncationSelection"
    },
    "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": "#/definitions/HyperDriveExperiment"
        }
      },
      "required": [
        "code",
        "result"
      ],
      "type": "object"
    }
  },
  "parameters": {
    "ArmScopeParameter": {
      "name": "armScope",
      "in": "path",
      "description": "The ARM scope passed in through URL with format:\r\n            subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.MachineLearningServices/workspaces/{workspaceName}/experiments/{experimentName}.\r\n",
      "required": true,
      "type": "string",
      "x-ms-skip-url-encoding": true,
      "x-ms-parameter-location": "method"
    }
  },
  "securityDefinitions": {
    "azure_auth": {
      "flow": "implicit",
      "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize",
      "scopes": {
        "user_impersonation": "impersonate your user account"
      },
      "type": "oauth2"
    }
  },
  "security": [
    {
      "azure_auth": [
        "user_impersonation"
      ]
    }
  ]
}