{
  "openapi": "3.0.0",
  "info": {
    "title": "MindsDB API",
    "description": "OpenAPI Specification for MindsDB's REST API. Each API Endpoint corresponds to a specific SQL Statement e.g POST /model => CREATE MODEL",
    "version": "0.0.1",
    "contact": {
      "email": "admin@mindsdb.com"
    },
    "license": {
      "name": "Server Side Public License (SSPL v1)",
      "url": "https://github.com/mindsdb/mindsdb/blob/main/LICENSE"
    }
  },
  "servers": [
    {
      "url": "https://cloud.mindsdb.com/v1/api",
      "description": "MindsDB Production cloud server"
    },
    {
      "url": "http://alpha.mindsdb.com/v1/api",
      "description": "MindsDB Alpha cloud server"
    },
    {
      "url": "http://127.0.0.1/v1/api",
      "description": "MindsDB local deployments"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY"
      }
    }
  },
  "paths": {
    "/databases": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Returns a list of database names.",
        "description": "This endpoint retrieves all databases created by the user.",
        "responses": {
          "200": {
            "description": "A JSON array of database names",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "example": "database name"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key error message",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Creates a new database connection.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "engine": {
                    "type": "string"
                  },
                  "user": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string"
                  },
                  "host": {
                    "type": "string"
                  },
                  "port": {
                    "type": "string"
                  },
                  "database": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Database was succesfully created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key error message",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "put": {
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Updates an existing database connection.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "user": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string"
                  },
                  "host": {
                    "type": "string"
                  },
                  "port": {
                    "type": "string"
                  },
                  "database": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Database was succesfully updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key error message",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/databases/{databaseName}": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Gets info about existing database.",
        "description": "This endpoint retrieves a specific database info.",
        "parameters": [
          {
            "name": "databaseName",
            "in": "path",
            "description": "databaseName to select",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A JSON object with database informations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key error message",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Database not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Deletes an existing database.",
        "description": "This endpoint deletes a database connection.",
        "parameters": [
          {
            "name": "databaseName",
            "in": "path",
            "description": "databaseName to delete",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A JSON array of database names",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key error message",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Database not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/models": {
      "post": {
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "This endpoint trains a new ML Model.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "project_name": {
                    "type": "string",
                    "description": "Name of the project where the model is created"
                  },
                  "predictor_name": {
                    "type": "string",
                    "description": "Name of the model to be created."
                  },
                  "integration_name": {
                    "type": "string",
                    "description": "Name of the database integration created"
                  },
                  "target_column": {
                    "type": "string",
                    "description": "Column to be predicted."
                  },
                  "query": {
                    "type": "string",
                    "description": "The SQL query to get the data"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Model training started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key error message",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Returns a list of models.",
        "description": "This endpoint retrieves the status of all models.",
        "responses": {
          "200": {
            "description": "A JSON array of models names",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "example": "model name"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key error message",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/models/{modelName}": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Gets info about specific model.",
        "description": "This endpoint retrieves the status of a specific model.",
        "parameters": [
          {
            "name": "modelName",
            "in": "path",
            "description": "The name of the model",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A JSON object with database informations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key error message",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Model not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "This endpoint fetches predictions from the model.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model_name": {
                    "type": "string",
                    "description": "Name of the project where the model is created"
                  },
                  "data": {
                    "type": "string",
                    "description": "The data for querying the model as SQL Statment or FILE"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Prediction data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key error message",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "str"
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Deletes an existing model.",
        "description": "This endpoint deletes a model.",
        "parameters": [
          {
            "name": "modelName",
            "in": "path",
            "description": "modelName to delete",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A JSON array of database names",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key error message",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Database not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/models/{modelName}/describe": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Describe a model",
        "description": "This endpoint returns the attributes of a specific model.",
        "parameters": [
          {
            "name": "modelName",
            "in": "path",
            "description": "The name of the model",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "features",
            "in": "query",
            "description": "Include how the model encoded data info",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A JSON object with model informations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key error message",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Model not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}