management_open_api.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "Model Server APIs",
    "description": "Model Server is a flexible and easy to use tool for serving deep learning models",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "options": {
        "operationId": "apiDescription",
        "parameters": [],
        "responses": {
          "200": {
            "description": "A openapi 3.0.1 descriptor",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "openapi",
                    "info",
                    "paths"
                  ],
                  "properties": {
                    "openapi": {
                      "type": "string"
                    },
                    "info": {
                      "type": "object"
                    },
                    "paths": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "code",
                    "type",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "Error code."
                    },
                    "type": {
                      "type": "string",
                      "description": "Error type."
                    },
                    "message": {
                      "type": "string",
                      "description": "Error message."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/models": {
      "get": {
        "description": "List registered models in Model Server.",
        "operationId": "listModels",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "description": "Use this parameter to specify the maximum number of items to return. When this value is present, Model Server does not return more than the specified number of items, but it might return fewer. This value is optional. If you include a value, it must be between 1 and 1000, inclusive. If you do not include a value, it defaults to 100.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": "100"
            }
          },
          {
            "in": "query",
            "name": "next_page_token",
            "description": "The token to retrieve the next set of results. Model Server provides the token when the response from a previous call has more results than the maximum page size.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "model_name_pattern",
            "description": "A model name filter to list only matching models.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "models"
                  ],
                  "properties": {
                    "nextPageToken": {
                      "type": "string",
                      "description": "Use this parameter in a subsequent request after you receive a response with truncated results. Set it to the value of NextMarker from the truncated response you just received."
                    },
                    "models": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "modelName",
                          "modelUrl"
                        ],
                        "properties": {
                          "modelName": {
                            "type": "string",
                            "description": "Name of the model."
                          },
                          "modelUrl": {
                            "type": "string",
                            "description": "URL of the model."
                          }
                        }
                      },
                      "description": "A list of registered models."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "code",
                    "type",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "Error code."
                    },
                    "type": {
                      "type": "string",
                      "description": "Error type."
                    },
                    "message": {
                      "type": "string",
                      "description": "Error message."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "description": "Register a new model in Model Server.",
        "operationId": "registerModel",
        "parameters": [
          {
            "in": "query",
            "name": "model_url",
            "description": "Model archive download url, support local file or HTTP(s) protocol. For S3, consider use pre-signed url.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "model_name",
            "description": "Name of model. This value will override modelName in MANIFEST.json if present.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "handler",
            "description": "Inference handler entry-point. This value will override handler in MANIFEST.json if present.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "runtime",
            "description": "Runtime for the model custom service code. This value will override runtime in MANIFEST.json if present.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "PYTHON",
                "PYTHON2",
                "PYTHON3"
              ]
            }
          },
          {
            "in": "query",
            "name": "batch_size",
            "description": "Inference batch size, default: 1.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": "1"
            }
          },
          {
            "in": "query",
            "name": "max_batch_delay",
            "description": "Maximum delay for batch aggregation, default: 100.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": "100"
            }
          },
          {
            "in": "query",
            "name": "response_timeout",
            "description": "Maximum time, in seconds, the Model Server waits for a response from the model inference code, default: 120.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": "2"
            }
          },
          {
            "in": "query",
            "name": "initial_workers",
            "description": "Number of initial workers, default: 0.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": "0"
            }
          },
          {
            "in": "query",
            "name": "synchronous",
            "description": "Decides whether creation of worker synchronous or not, default: false.",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": "false"
            }
          },
          {
            "in": "query",
            "name": "preload_model",
            "description": "Decides if model should be preloaded, default: false.",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": "false"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Model registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "Error type."
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "Error type."
                    }
                  }
                }
              }
            }
          },
          "210": {
            "description": "Partial Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "Error type."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "code",
                    "type",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "Error code."
                    },
                    "type": {
                      "type": "string",
                      "description": "Error type."
                    },
                    "message": {
                      "type": "string",
                      "description": "Error message."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Model not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "code",
                    "type",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "Error code."
                    },
                    "type": {
                      "type": "string",
                      "description": "Error type."
                    },
                    "message": {
                      "type": "string",
                      "description": "Error message."
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Model already registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "code",
                    "type",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "Error code."
                    },
                    "type": {
                      "type": "string",
                      "description": "Error type."
                    },
                    "message": {
                      "type": "string",
                      "description": "Error message."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "code",
                    "type",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "Error code."
                    },
                    "type": {
                      "type": "string",
                      "description": "Error type."
                    },
                    "message": {
                      "type": "string",
                      "description": "Error message."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/models/{model_name}": {
      "get": {
        "description": "Provides detailed information about the specified model.",
        "operationId": "describeModel",
        "parameters": [
          {
            "in": "path",
            "name": "model_name",
            "description": "Name of model to describe.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "modelName",
                    "modelVersion",
                    "modelUrl",
                    "minWorkers",
                    "maxWorkers",
                    "status",
                    "workers",
                    "metrics"
                  ],
                  "properties": {
                    "modelName": {
                      "type": "string",
                      "description": "Name of the model."
                    },
                    "modelVersion": {
                      "type": "string",
                      "description": "Version of the model."
                    },
                    "modelUrl": {
                      "type": "string",
                      "description": "URL of the model."
                    },
                    "minWorkers": {
                      "type": "integer",
                      "description": "Configured minimum number of worker."
                    },
                    "maxWorkers": {
                      "type": "integer",
                      "description": "Configured maximum number of worker."
                    },
                    "batchSize": {
                      "type": "integer",
                      "description": "Configured batch size."
                    },
                    "maxBatchDelay": {
                      "type": "integer",
                      "description": "Configured maximum batch delay in ms."
                    },
                    "status": {
                      "type": "string",
                      "description": "Overall health status of the model"
                    },
                    "workers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "startTime",
                          "status"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Worker id"
                          },
                          "startTime": {
                            "type": "string",
                            "description": "Worker start time"
                          },
                          "gpu": {
                            "type": "boolean",
                            "description": "If running on GPU"
                          },
                          "status": {
                            "type": "string",
                            "description": "Worker status",
                            "enum": [
                              "READY",
                              "LOADING",
                              "UNLOADING"
                            ]
                          }
                        }
                      },
                      "description": "A list of active backend workers."
                    },
                    "metrics": {
                      "type": "object",
                      "required": [
                        "rejectedRequests",
                        "waitingQueueSize",
                        "requests"
                      ],
                      "properties": {
                        "rejectedRequests": {
                          "type": "integer",
                          "description": "Number requests has been rejected in last 10 minutes."
                        },
                        "waitingQueueSize": {
                          "type": "integer",
                          "description": "Number requests waiting in the queue."
                        },
                        "requests": {
                          "type": "integer",
                          "description": "Number requests processed in last 10 minutes."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "code",
                    "type",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "Error code."
                    },
                    "type": {
                      "type": "string",
                      "description": "Error type."
                    },
                    "message": {
                      "type": "string",
                      "description": "Error message."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "put": {
        "description": "Configure number of workers for a model, This is a asynchronous call by default. Caller need to call describeModel check if the model workers has been changed.",
        "operationId": "setAutoScale",
        "parameters": [
          {
            "in": "path",
            "name": "model_name",
            "description": "Name of model to describe.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "min_worker",
            "description": "Minimum number of worker processes.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": "1"
            }
          },
          {
            "in": "query",
            "name": "max_worker",
            "description": "Maximum number of worker processes.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": "1"
            }
          },
          {
            "in": "query",
            "name": "number_gpu",
            "description": "Number of GPU worker processes to create.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": "0"
            }
          },
          {
            "in": "query",
            "name": "synchronous",
            "description": "Decides whether the call is synchronous or not, default: false.",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": "false"
            }
          },
          {
            "in": "query",
            "name": "timeout",
            "description": "Waiting up to the specified wait time if necessary for a worker to complete all pending requests. Use 0 to terminate backend worker process immediately. Use -1 for wait infinitely.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": "-1"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Model workers updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "Error type."
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "Error type."
                    }
                  }
                }
              }
            }
          },
          "210": {
            "description": "Partial Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "Error type."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "code",
                    "type",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "Error code."
                    },
                    "type": {
                      "type": "string",
                      "description": "Error type."
                    },
                    "message": {
                      "type": "string",
                      "description": "Error message."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Model not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "code",
                    "type",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "Error code."
                    },
                    "type": {
                      "type": "string",
                      "description": "Error type."
                    },
                    "message": {
                      "type": "string",
                      "description": "Error message."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "code",
                    "type",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "Error code."
                    },
                    "type": {
                      "type": "string",
                      "description": "Error type."
                    },
                    "message": {
                      "type": "string",
                      "description": "Error message."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "description": "Unregister a model from Model Server. This is an asynchronous call by default. Caller can call listModels to confirm if all the works has be terminated.",
        "operationId": "unregisterModel",
        "parameters": [
          {
            "in": "path",
            "name": "model_name",
            "description": "Name of model to unregister.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "synchronous",
            "description": "Decides whether the call is synchronous or not, default: false.",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": "false"
            }
          },
          {
            "in": "query",
            "name": "timeout",
            "description": "Waiting up to the specified wait time if necessary for a worker to complete all pending requests. Use 0 to terminate backend worker process immediately. Use -1 for wait infinitely.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": "-1"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Model unregistered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "Error type."
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "Error type."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Model not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "code",
                    "type",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "Error code."
                    },
                    "type": {
                      "type": "string",
                      "description": "Error type."
                    },
                    "message": {
                      "type": "string",
                      "description": "Error message."
                    }
                  }
                }
              }
            }
          },
          "408": {
            "description": "Request Timeout Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "code",
                    "type",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "Error code."
                    },
                    "type": {
                      "type": "string",
                      "description": "Error type."
                    },
                    "message": {
                      "type": "string",
                      "description": "Error message."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "code",
                    "type",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "type": "integer",
                      "description": "Error code."
                    },
                    "type": {
                      "type": "string",
                      "description": "Error type."
                    },
                    "message": {
                      "type": "string",
                      "description": "Error message."
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}