openapi.yml

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: 'http://127.0.0.1:47334/'
    description: MindsDB local deployments
components:
  schemas:
    Database:
      type: object
      properties:
        name:
          type: string
        engine:
          type: string
          description: Handler used to create this database (e.g. postgres)
        type:
          type: string
          description: Type of database (data | project | system)
    Model:
      type: object
      properties:
        name:
          type: string
        accuracy:
          type: number
          description: Accuracy of trained model between 0 and 1
        active:
          type: boolean
          description: Whether or not this model is currently the active version
        version:
          type: number
          description: Version of this model
        status:
          type: string
          description: Current status of this model (generating | creating | complete | error)
        predict:
          type: string
          description: Column name that this model predicts
        mindsdb_version:
          type: string
          description: MindsDB version associated with this model
        error:
          type: string
          description: Error encountered during training, if applicable
        fetch_data_query:
          type: string
          description: SQL query used to fetch training data for this model
        created_at:
          type: string
          description: Time model was created at in YYYY-MM-DD HH:MM:SS format (trained models only)
        training_time:
          type: string
          description: How long training this model took in HH:MM:SS format (trained models only)
        update:
          type: string
          description: Set to "available" when a new version of MindsDB is available that makes the model obsolete, or when new data is available in the data that was used to train the model (trained models only).
    Project:
      type: object
      properties:
        name:
          type: string
    Table:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          description: Type of table (data | view)
    View:
      type: object
      properties:
        name:
          type: string
        query:
          type: string
          description: SELECT query used to create the view
    File:
      type: object
      properties:
        columns:
          type: array
          items:
            type: string
        name:
          type: string
        row_count:
          type: number
    Skill:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          description: Type of skill (text2sql | knowledge_base).
        source: # used when type = knowledge_base
          type: string
          description: Used to store a knowledge_base object when type is set to knowledge_base.
        database: # used when type = text2sql
          type: string
          description: Used to store a data source connection when type is set to text2sql.
        tables: # used when type = text2sql
          type: array
          items:
            type: string
          description: Used to store table(s) names when type is set to text2sql.
        description:
          type: string
          description: Skill description is important for an agent to decide which skill to use. 
    Agent:
      type: object
      properties:
        name:
          type: string
        model:
          type: string
          description: A conversational model used by an agent
        skills:
          type: array
          items:
            type: string
          description: One or more skills that an agent can use
    Chatbot:
      type: object
      properties:
        name:
          type: string
        database_name:
          type: string
          description: Name of the connection to a chat app like Slack or MS Teams
        agent_name:
          type: string
          description: Agent object created beforehand. Alternatively, provide a large language model (LLM) using the `model_name` parameter.
    Job:
      type: object
      properties:
        name:
          type: string
        query:
          type: string
          description: Tasks to be executed by the job
        if_query:
          type: string
          description: Optional. Condition to be fulfilled before the job executes
        start_at:
          type: string
          format: date-time
          description: Optional. Start date/time of the job
        end_at:
          type: string
          format: date-time
          description: Optional. End date/time of the job
        schedule_str:
          type: string
          description: Periodicity of the job (e.g. every 1 minute)
paths:
  '/api/databases':
    get:
      summary: Returns a list of database names.
      description: Gets all databases created by the user.
      responses:
        '200':
          description: A JSON array of database names
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Database'
        '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:
      summary: Creates a new database connection.
      description: Creates a new database connection. The example parameters below are for connecting to [MySQL](/data-integrations/mysql). See [here](/data-integrations/all-data-integrations) for which parameters to use for your datasource.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                database:
                  type: object
                  properties:
                    name:
                      type: string
                    engine:
                      type: string
                    parameters:
                      type: object
                      description: Parameters used to connect to your data source. These example parameters are for connecting to [MySQL](/data-integrations/mysql). See [here](/data-integrations/all-data-integrations) for which parameters to use for your datasource.
                      properties:
                        user:
                          type: string
                        password:
                          type: string
                        host:
                          type: string
                        port:
                          type: string
                        database:
                          type: string
      responses:
        # OpenAPI spec defines '200' status as a successful operation, so even though the
        # response code is '201', we need to use '200' so docs are properly generated.
        '200':
          description: The created database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '400':
          description: Bad request format
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '409':
          description: Database already exists
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/databases/status':
    post:
      summary: Checks the status of a database connection.
      description: Checks the status of a database connection by validating the connection parameters.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                engine:
                  type: string
              required: [engine]
              additionalProperties: true
      responses:
        '200':
          description: Response always returns HTTP 200, but status is inside the body
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: ["success", "connection_error", "redirect_required"]
                  detail: 
                    type: string
                    description: Additional information about any errors
                  redirect_url: 
                    type: string
                    description: URL to redirect to if status is "redirect_required"
                  required: [status]
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/databases/{databaseName}':
    get:
      summary: Gets info about existing database.
      description: Gets info about an existing database.
      parameters:
        - name: databaseName
          in: path
          description: Name of existing database
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON object with database informations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '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
    put:
      summary: Updates an existing database connection.
      description: Updates an existing database connection, or creates a new connection if one doesn't exist. The example parameters below are for updating a [MySQL](/data-integrations/mysql) connection. See [here](/data-integrations/all-data-integrations) for which parameters to use for your datasource.
      parameters:
        - name: databaseName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                database:
                  type: object
                  properties:
                    engine:
                      type: string
                    parameters:
                      type: object
                      description: Parameters used to connect to your data source. These example parameters are for connecting to [MySQL](/data-integrations/mysql). See [here](/data-integrations/all-data-integrations) for which parameters to use for your datasource.
                      properties:
                        user:
                          type: string
                        password:
                          type: string
                        host:
                          type: string
                        port:
                          type: string
                        database:
                          type: string
      responses:
        '200':
          description: Database was successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '400':
          description: Bad request format
          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
    delete:
      summary: Deletes an existing database.
      description: Deletes an existing database connection by name.
      parameters:
        - name: databaseName
          in: path
          description: Name of existing database to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An empty response indicates success
          content:
            application/json:
              schema:
                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
  '/api/projects':
    get:
      summary: Returns a list of projects.
      description: Gets all projects created by the user.
      responses:
        '200':
          description: A JSON array of projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '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
  '/api/projects/{projectName}':
    get:
      summary: Get a project by name.
      description: Gets a project created by the user.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The returned project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/models':
    post:
      summary: This endpoint trains a new ML Model.
      description: Starts training a new Machine Learning model.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: The SQL CREATE MODEL statement used to train this model. See the [CREATE MODEL](https://docs.mindsdb.com/sql/create/model) statement 
      responses:
        '200':
          description: Model training started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '400':
          description: Bad request
          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: Project not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    get:
      summary: Returns a list of models.
      description: Gets info about all models in the project.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of models names
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Model'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/models/{modelName}':
    get:
      summary: Gets info about specific model.
      description: Gets info for a specific model in the project.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
        - name: modelName
          in: path
          description: The name of the model
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Model information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '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
    delete:
      summary: Deletes an existing model.
      description: Deletes a model in the project.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
        - name: modelName
          in: path
          description: The name of the model
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Empty response if delete is successful
          content:
            application/json:
              schema:
                type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project or 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
  '/api/projects/{projectName}/models/{modelName}/predict':
    post:
      summary: This endpoint fetches predictions from the model.
      description: Uses this model to make a prediction for values of new data.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
        - name: modelName
          in: path
          description: The name of the model
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              properties:
                data:
                  type: object
                  description: The data for querying the model as key/value e.g column name/value. Example with [home rental prices](https://docs.mindsdb.com/sql/tutorials/home-rentals) - [{"sqft":823}]
      responses:
        '200':
          description: Model queried succesfully
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
                  description: Prediction object that contains data columns and the target value, confidence, lower and upper bound.
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project or 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
  '/api/projects/{projectName}/models/{modelName}/describe':
    get:
      summary: Describe a model
      description: Gets the attributes of a specific model.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
        - name: modelName
          in: path
          description: The name of the model
          required: true
          schema:
            type: string
      requestBody:
          content:
            application/json:
              schema:
                type: object
                properties:
                  attribute:
                    type: string
                    description: Attribute of the model to describe. See our [DESCRIBE documentation](https://docs.mindsdb.com/sql/api/describe). E.g. info, features, model
      responses:
        '200':
          description: A JSON object with model informations
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
                  description: Array containing model information
        '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
  '/api/projects/{projectName}/views':
    post:
      summary: This endpoint creates a view which is a result-set of the SELECT statement.
      description: Creates a [view](https://docs.mindsdb.com/sql/create/view) from a SELECT statement.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                view:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Name of the view
                    query:
                      type: string
                      description: The SQL query that will save the result-set in a view.
      responses:
        '200':
          description: View created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/View'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    get:
      summary: List all views in a project
      description: Gets all views in a project.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON object with view names
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/View'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/views/{viewName}':
    get:
      summary: SELECT from VIEW
      description: Gets a single view.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
        - name: viewName
          in: path
          description: The name of the view
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON object with VIEW data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/View'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: View or project 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:
      summary: Deletes an existing view.
      description: Deletes an existing view in the project.
      parameters:
        - name: projectName
          in: path
          description: Project name the view is in
          required: true
          schema:
            type: string
        - name: viewName
          in: path
          description: View name to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Succesfully deleted
          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: View or projectnot found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    put:
      summary: Updates an existing view.
      description: Updates an existing view, or creates a new view if one doesn't exist.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
        - name: viewName
          in: path
          description: The name of the view
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                view:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Name of the view
                    query:
                      type: string
                      description: The SQL query that will save the result-set in a view.
      responses:
        '200':
          description: View was successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/View'
        '400':
          description: Bad request format
          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
  '/api/databases/{databaseName}/tables':
    post:
      summary: This endpoint creates a new table with the predictions result-set.
      description: Creates a new table from a select query. See [CREATE table documentation](https://docs.mindsdb.com/sql/create/table).
      parameters:
      - name: databaseName
        in: path
        description: Name of the database
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                table:
                  type: object
                  properties:
                    name:
                      type: string
                    select:
                      type: string
                      description: SELECT statement to create the table from
                    replace:
                      type: boolean
                      description: Whether or not to delete a pre-existing table before creating it
      responses:
        '200':
          description: Table created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Table'
        '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
    get:
      summary: Returns a list of tables in a database.
      description: Gets metadata for all tables in a database.
      parameters:
        - name: databaseName
          in: path
          description: The name of the database
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of tables
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Table'
        '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
  '/api/databases/{databaseName}/tables/{tableName}':
    get:
      summary: SELECT from Table
      description: Gets metadata for a table in a database.
      parameters:
        - name: databaseName
          in: path
          description: The name of the database
          required: true
          schema:
            type: string
        - name: tableName
          in: path
          description: The name of the table
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON object with SELECT data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Table'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Table or 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:
      summary: Deletes an existing table.
      description: Deletes a table in a database.
      parameters:
        - name: databaseName
          in: path
          description: The name of the database
          required: true
          schema:
            type: string
        - name: tableName
          in: path
          description: Table name to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully deleted
          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: Table or 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
  '/api/projects/{projectName}/skills':
    get:
      summary: Returns a list of all created skills.
      description: Gets all skills created by the user.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of skill names
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Skill'
        '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:
      summary: Creates a new skill.
      description: Creates a new skill.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                skill:
                  type: object
                  properties:
                    name:
                      type: string
                    type:
                      type: string
                      description: Type of skill (text2sql | knowledge_base).
                    source: # used when type = knowledge_base
                      type: string
                      description: Used to store a knowledge_base object when type is set to knowledge_base.
                    database: # used when type = text2sql
                      type: string
                      description: Used to store a data source connection when type is set to text2sql.
                    tables: # used when type = text2sql
                      type: array
                      items:
                        type: string
                      description: Used to store table(s) names when type is set to text2sql.
                    description:
                      type: string
                      description: Skill description is important for an agent to decide which skill to use.
      responses:
        '200':
          description: Created a skill
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Skill'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '400':
          description: Bad request format
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '409':
          description: Skill already exists
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/skills/{skillName}':
    get:
      summary: Gets info about existing skills.
      description: Gets info about an existing skill.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
        - name: skillName
          in: path
          description: Name of existing skill
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON object with skills
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Skill'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Skill not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    put:
      summary: Updates an existing skill.
      description: Updates an existing skill, or creates a new skill if one doesn't exist.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
        - name: skillName
          in: path
          description: The name of the skill
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                skill:
                  type: object
                  properties:
                    name:
                      type: string
                    type:
                      type: string
                      description: Type of skill (text2sql | knowledge_base).
                    source: # used when type = knowledge_base
                      type: string
                      description: Used to store a knowledge_base object when type is set to knowledge_base.
                    database: # used when type = text2sql
                      type: string
                      description: Used to store a data source connection when type is set to text2sql.
                    tables: # used when type = text2sql
                      type: array
                      items:
                        type: string
                      description: Used to store table(s) names when type is set to text2sql.
                    description:
                      type: string
                      description: Skill description is important for an agent to decide which skill to use.
      responses:
        '200':
          description: Skill was successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Skill'
        '400':
          description: Bad request format
          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
    delete:
      summary: Deletes an existing skill.
      description: Deletes an existing skill by name.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
        - name: skillName
          in: path
          description: Name of existing skill to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An empty response indicates success
          content:
            application/json:
              schema:
                type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Skill not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/agents':
    get:
      summary: Returns a list of all created agents.
      description: Gets all agents created by the user.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of skill names
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Agent'
        '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:
      summary: Creates a new agent.
      description: Creates a new agent.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                agent:
                  type: object
                  properties:
                    name:
                      type: string
                    model:
                      type: string
                      description: A conversational model used by an agent
                    skills:
                      type: array
                      items:
                        type: string
                      description: One or more skills that an agent can use
      responses:
        '200':
          description: Created an agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '400':
          description: Bad request format
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '409':
          description: Agent already exists
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/agents/{agentName}':
    get:
      summary: Gets info about existing agent.
      description: Gets info about an existing agent.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
        - name: agentName
          in: path
          description: Name of existing agent
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON object with skills
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    put:
      summary: Updates an existing agent.
      description: Updates an existing agent, or creates a new agent if one doesn't exist.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
        - name: agentName
          in: path
          description: The name of the agent
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                agent:
                  type: object
                  properties:
                    name:
                      type: string
                    model:
                      type: string
                      description: A conversational model used by an agent
                    skills:
                      type: array
                      items:
                        type: string
                      description: One or more skills that an agent can use
      responses:
        '200':
          description: Agent was successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          description: Bad request format
          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
    delete:
      summary: Deletes an existing agent.
      description: Deletes an existing agent by name.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
        - name: agentName
          in: path
          description: Name of existing agent to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An empty response indicates success
          content:
            application/json:
              schema:
                type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/agents/{agentName}/completions':
    post:
      summary: Quesries an agent.
      description: Quesries an agent.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
        - name: agentName
          in: path
          description: The name of the agent
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  items:
                    type: object
                    properties:
                      question:
                        type: string
                        description: The question being asked
                      answer:
                        type: string
                        nullable: true
                        description: The answer to the question (can be null)
      responses:
        '200':
          description: Message submission successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: object
                    properties:
                      role:
                        type: string
                        description: The role of the responder
                      content:
                        type: string
                        description: The content of the response
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '400':
          description: Bad request format
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/chatbots':
    get:
      summary: Returns a list of all created chatbots.
      description: Gets all chatbots created by the user.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of skill names
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Chatbot'
        '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:
      summary: Creates a new chatbot.
      description: Creates a new chatbot.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                chatbot:
                  type: object
                  properties:
                    name:
                      type: string
                    database_name:
                      type: string
                      description: Name of the connection to a chat app like Slack or MS Teams
                    agent_name:
                      type: string
                      description: Agent object created beforehand. Alternatively, provide a large language model (LLM) using the `model_name` parameter.
      responses:
        '200':
          description: Created a chatbot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chatbot'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '400':
          description: Bad request format
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '409':
          description: Chatbot already exists
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/chatbots/{chatbotName}':
    get:
      summary: Gets info about existing chatbots.
      description: Gets info about an existing chatbot.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
        - name: chatbotName
          in: path
          description: Name of existing chatbot
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON object with chatbots
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chatbot'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Chatbot not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    put:
      summary: Updates an existing chatbot.
      description: Updates an existing chatbot, or creates a new chatbot if one doesn't exist.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
        - name: chatbotName
          in: path
          description: The name of the chatbot
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                chatbot:
                  type: object
                  properties:
                    name:
                      type: string
                    database:
                      type: string
                      description: Connection to a chat app like Slack or MS Teams
                    agent:
                      type: string
                      description: Agent object created beforehand
      responses:
        '200':
          description: Chatbot was successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chatbot'
        '400':
          description: Bad request format
          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
    delete:
      summary: Deletes an existing chatbot.
      description: Deletes an existing chatbot by name.
      parameters:
        - name: projectName
          in: path
          description: The name of the project where agent resides
          required: true
          schema:
            type: string
        - name: chatbotName
          in: path
          description: Name of existing chatbot to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An empty response indicates success
          content:
            application/json:
              schema:
                type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Chatbot not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/files':
    get:
      summary: List all files uploaded to MindsDB.
      description: Gets all files uploaded to MindsDB.
      responses:
        '200':
          description: A JSON array of file names
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/File'
        '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
  '/api/files/{fileName}':
    delete:
      summary: Deletes an existing file.
      description: Deletes an existing file.
      parameters:
        - name: fileName
          in: path
          description: File name to be deleted
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Succesfully deleted
          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:
      summary: Upload a new file.
      description: Upload a new file.
      parameters:
        - name: fileName
          in: path
          description: The name of the file
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload
                original_file_name:
                  type: string
                  description: The original name of the file (optional)
      responses:
        '200':
          description: View was successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        '400':
          description: Bad request format
          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
  '/api/projects/{projectName}/jobs':
    post:
      summary: This endpoint creates a new Job.
      description: Create a job to automate tasks.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the job
                query:
                  type: string
                  description: Tasks to be executed by the job
                if_query:
                  type: string
                  description: Optional. Condition to be fulfilled before the job executes
                start_at:
                  type: string
                  format: date-time
                  description: Optional. Start date/time of the job
                end_at:
                  type: string
                  format: date-time
                  description: Optional. End date/time of the job
                schedule_str:
                  type: string
                  description: Periodicity of the job (e.g. every 1 minute)
      responses:
        '200':
          description: Job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Bad request
          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: Project not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    get:
      summary: Returns a list of jobs.
      description: Gets info about all jobs in the project.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of job names
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Job'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/jobs/{jobName}':
    get:
      summary: Gets info about specific job.
      description: Gets info for a specific job in the project.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
        - name: jobName
          in: path
          description: The name of the job
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Job 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:
      summary: Deletes an existing job.
      description: Deletes a job in the project.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
        - name: jobName
          in: path
          description: The name of the job
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Empty response if delete is successful
          content:
            application/json:
              schema:
                type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project or job not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string