swagger.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Voyager APIs",
    "contact": {
      "email": "cbh778899@outlook.com"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "http://localhost:8000"
    }
  ],
  "tags": [
    {
      "name": "Index",
      "description": "Index of Voyager project"
    },
    {
      "name": "Chat",
      "description": "v1 Chat APIs"
    },
    {
      "name": "Embedding",
      "description": "v1 Embedding APIs"
    },
    {
      "name": "Token",
      "description": "v1 Token APIs"
    },
    {
      "name": "Version",
      "description": "v1 Version APIs"
    },
    {
      "name": "File",
      "description": "v1 File APIs"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": [
          "Index"
        ],
        "summary": "Route of this page",
        "description": "Route to get this page"
      }
    },
    "/healthy": {
      "get": {
        "tags": [
          "Index"
        ],
        "summary": "Route for healthy check",
        "description": "If got response, means the server is running normally",
        "responses": {
          "200": {
            "description": "Server works normally",
            "content": {
              "text/plain; charset=utf-8": {
                "examples": {
                  "ok": {
                    "value": "ok"
                  }
                }
              }
            }
          },
          "500": {
            "description": "The server is not running normally, please check your server."
          }
        }
      }
    },
    "/stats": {
      "get": {
        "tags": [
          "Index"
        ],
        "summary": "Route to check stats",
        "description": "Graphical server stats, Click [here](/stats) to get the page.",
        "responses": {
          "200": {
            "description": "Returns The page of checking stats",
            "content": {
              "text/html": {}
            }
          }
        }
      }
    },
    "/chatbox": {
      "get": {
        "tags": [
          "Index"
        ],
        "summary": "Route to embed chatbot",
        "description": "Please see this [README](https://github.com/SkywardAI/voyager?tab=readme-ov-file#embed-your-chatbot-into-website).",
        "parameters": [
          {
            "in": "query",
            "name": "base_url",
            "type": "string",
            "description": "The base url of request, usually the url of this page you are looking at. Default http://localhost:8000."
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the load script, usually load with script tag in HTML",
            "content": {
              "application/json; charset=utf-8": {}
            }
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "tags": [
          "Chat"
        ],
        "summary": "AI chat completion",
        "description": "Start a conversation with given messages as context",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "description": "Request body of AI chat completion",
              "schema": {
                "$ref": "#/components/schemas/CompletionRequest"
              },
              "example": {
                "messages": [
                  {
                    "role": "system",
                    "content": "You are a helpful assistant who helps users solve their questions."
                  },
                  {
                    "role": "user",
                    "content": "Hello, tell me more about you!"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OpenAI like response",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/CompletionResponseStream"
                    },
                    {
                      "$ref": "#/components/schemas/CompletionResponseEntire"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Some errors occured"
          },
          "401": {
            "description": "Not authorized"
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/v1/chat/rag-completions": {
      "post": {
        "tags": [
          "Chat"
        ],
        "summary": "AI chat completion with RAG dataset.",
        "description": "Start a conversation with given messages and QAs from dataset as context. Please load dataset and pass the correct dataset name to make it work.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompletionRequest"
              },
              "example": {
                "messages": [
                  {
                    "role": "system",
                    "content": "You are a helpful assistant who helps users solve their questions."
                  },
                  {
                    "role": "user",
                    "content": "tell me something interest about massachusetts"
                  }
                ],
                "dataset_name": "aisuko/squad01-v2"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "content": {
                      "$ref": "#/components/schemas/CompletionResponseEntire"
                    },
                    "rag_context": {
                      "type": "object",
                      "properties": {
                        "context": {
                          "type": "string",
                          "examples": [
                            "Questioin:In what year did Massachusetts first require children to be educated in schools? Answer:1852"
                          ]
                        },
                        "identifier": {
                          "type": "string",
                          "examples": [
                            "Private_school"
                          ]
                        },
                        "_distance": {
                          "type": "number",
                          "examples": [
                            0.4810483455657959
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Some errors occured"
          },
          "401": {
            "description": "Not authorized"
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/v1/embeddings": {
      "post": {
        "tags": [
          "Embedding"
        ],
        "summary": "Get embedding of input",
        "description": "Get the embedding value of given input, in OpenAI format",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "input": {
                    "type": "string",
                    "examples": [
                      "Hello, world!"
                    ]
                  },
                  "model": {
                    "type": "string",
                    "description": "You can pass model, but this won't work at current stage",
                    "examples": [
                      "all-MiniLM-L6-v2"
                    ]
                  },
                  "encoding_format": {
                    "type": "string",
                    "description": "You can pass encoding_format, but this won't work as we currently only support float.",
                    "examples": [
                      "float"
                    ]
                  }
                },
                "required": [
                  "input"
                ],
                "example": {
                  "input": "Hello, world!",
                  "model": "all-MiniLM-L6-v2"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Everything works normal, get embedding result in OpenAI format",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "object": {
                      "type": "string",
                      "examples": [
                        "list"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "object": {
                            "type": "string",
                            "examples": [
                              "embedding"
                            ]
                          },
                          "embedding": {
                            "type": "array",
                            "items": {
                              "type": "number",
                              "examples": [
                                -0.02184351161122322,
                                0.049017686396837234,
                                0.06728602200746536
                              ]
                            },
                            "description": "The length should be exactly 384 items",
                            "example": [
                              -0.02184351161122322,
                              0.049017686396837234,
                              0.06728602200746536,
                              0.06581537425518036,
                              -0.05950690433382988,
                              -0.08613293617963791,
                              "*** totally 384 floats ***"
                            ]
                          },
                          "index": {
                            "type": "integer",
                            "examples": [
                              0
                            ]
                          }
                        }
                      }
                    },
                    "model": {
                      "type": "string",
                      "examples": [
                        "all-MiniLM-L6-v2"
                      ]
                    },
                    "usage": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "prompt_tokens": {
                            "type": "integer",
                            "examples": [
                              0
                            ]
                          },
                          "total_tokens": {
                            "type": "integer",
                            "examples": [
                              0
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Some errors occured"
          },
          "401": {
            "description": "Not authorized"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/v1/embeddings/dataset": {
      "post": {
        "tags": [
          "Embedding"
        ],
        "summary": "Loads dataset into database",
        "description": "Load a dataset from url or directly pass a dataset array. Requires either url or json specified.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UploadDatasetRequest",
                "required": [
                  "name"
                ],
                "example": {
                  "name": "aisuko/squad01-v2",
                  "url": "https://datasets-server.huggingface.co/rows?dataset=aisuko%2Fsquad01-v2&config=default&split=validation&offset=0&length=100"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully loaded dataset"
          },
          "401": {
            "description": "Not authorized"
          },
          "422": {
            "description": "`Name` or neither `url` nor `json` not specified."
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/v1/token/api-key": {
      "get": {
        "tags": [
          "Token"
        ],
        "summary": "Get api key",
        "description": "The route to get api key, please keep it yourself.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "api-key": {
                      "type": "string",
                      "examples": [
                        "voy-5uh12i196p8rqqgo3pbdmoaj1teit9clgk9ujkk0n91o"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/version": {
      "get": {
        "summary": "Get engine versions",
        "description": "Get version of various engines used by this project",
        "tags": [
          "Version"
        ],
        "responses": {
          "200": {
            "description": "Get a json of versions",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "inference_engine_version": {
                      "type": "string",
                      "examples": [
                        "server--b1-2321a5e"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/files": {
      "post": {
        "summary": "Upload a file",
        "description": "Upload a file to the voyager endpoint",
        "tags": [
          "File"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "description": "Request body for file upload",
              "schema": {
                "type": "object",
                "properties": {
                  "input": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upload a file successfully",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "id": {
                      "type": "string",
                      "examples": [
                        "file_abc123"
                      ]
                    },
                    "bytes": {
                      "type": "integer",
                      "examples": [
                        120001
                      ]
                    },
                    "created_at": {
                      "type": "integer",
                      "examples": [
                        1677610603
                      ]
                    },
                    "filename": {
                      "type": "string",
                      "examples": [
                        "test.json"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Incorrect or missing file"
          },
          "401": {
            "description": "Not authorized"
          },
          "500": {
            "description": "Server error"
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      },
      "get": {
        "summary": "Get all files",
        "description": "Get all files metadata available in the table",
        "tags": [
          "File"
        ],
        "responses": {
          "200": {
            "description": "Get all files metadata successfully",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "properties": {
                          "id": {
                            "type": "string",
                            "examples": [
                              "file_abc123"
                            ]
                          },
                          "bytes": {
                            "type": "number",
                            "examples": [
                              "120001"
                            ]
                          },
                          "created_at": {
                            "type": "number",
                            "examples": [
                              "1677610603"
                            ]
                          },
                          "filename": {
                            "type": "string",
                            "examples": [
                              "test.json"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Not authorized"
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "CompletionRequest": {
        "properties": {
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "role": {
                  "type": "string",
                  "examples": [
                    "system",
                    "user",
                    "assistant"
                  ]
                },
                "content": {
                  "type": "string",
                  "examples": [
                    "You are a helpful assistant who helps users solve their questions.",
                    "Hi, what can you do?"
                  ]
                }
              }
            }
          },
          "max_tokens": {
            "type": "integer",
            "examples": [
              32,
              128,
              512
            ]
          },
          "end": {
            "type": "array",
            "description": "When AI outputs the end pattern, end response.",
            "items": {
              "type": "string",
              "examples": [
                "<|user|>"
              ]
            }
          },
          "stream": {
            "type": "boolean",
            "description": "If set to `true`, AI will response streamed."
          }
        },
        "required": [
          "messages"
        ]
      },
      "RAGCompletionRequest": {
        "properties": {
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "role": {
                  "type": "string",
                  "examples": [
                    "system",
                    "user",
                    "assistant"
                  ]
                },
                "content": {
                  "type": "string",
                  "examples": [
                    "You are a helpful assistant who helps users solve their questions.",
                    "Hi, what can you do?"
                  ]
                }
              }
            }
          },
          "max_tokens": {
            "type": "integer",
            "examples": [
              32,
              128,
              512
            ]
          },
          "end": {
            "type": "array",
            "description": "When AI outputs the end pattern, end response.",
            "items": {
              "type": "string",
              "examples": [
                "<|user|>"
              ]
            }
          },
          "stream": {
            "type": "boolean",
            "description": "If set to `true`, AI will response streamed."
          },
          "dataset_name": {
            "type": "string",
            "examples": [
              "aisuko/squad01-v2"
            ]
          }
        },
        "required": [
          "messages",
          "dataset_name"
        ]
      },
      "UploadDatasetRequest": {
        "properties": {
          "name": {
            "type": "string",
            "description": "Dataset name",
            "examples": [
              "aisuko/squad01-v2"
            ]
          },
          "url": {
            "type": "string",
            "description": "URL to download dataset",
            "examples": [
              "https://datasets-server.huggingface.co/rows?dataset=aisuko%2Fsquad01-v2&config=default&split=validation&offset=0&length=100"
            ]
          },
          "json": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "identifier": {
                  "type": "string",
                  "description": "Identifier of the row, not necessarily unique",
                  "examples": [
                    "Chloroplast"
                  ]
                },
                "context": {
                  "type": "string",
                  "description": "Context to store in vector DB and pass to inference engine.",
                  "examples": [
                    "Questioin:When were stromules discovered? Answer:1962"
                  ]
                }
              }
            }
          },
          "force": {
            "type": "boolean",
            "description": "If specified, delete previous records of current dataset and load dataset into database.",
            "examples": [
              false
            ]
          },
          "keep_records": {
            "type": "boolean",
            "description": "If `force` is specified and `keep_records` is `true`, keeps records and load data into database. This can cause duplicate data in DB.",
            "examples": [
              false
            ]
          }
        }
      },
      "CompletionResponseEntire": {
        "description": "Response of completion, where `stream=false`",
        "properties": {
          "id": {
            "type": "string",
            "description": "The id passed through `Authorization` header",
            "examples": [
              "voy-5uh12i196p8rqqgo3pbdmoaj1teit9clgk9ujkk0n91o"
            ]
          },
          "object": {
            "type": "string",
            "examples": [
              "chat.completion"
            ]
          },
          "created": {
            "type": "integer",
            "examples": [
              1722576434241
            ]
          },
          "model": {
            "type": "string",
            "examples": [
              "Phi3-mini-4k-instruct-Q4.gguf"
            ]
          },
          "system_fingerprint": {
            "type": "fp_2flh9v7kboo"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "message": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "role": {
                        "type": "string",
                        "examples": [
                          "assistant"
                        ]
                      },
                      "message": {
                        "content": "string",
                        "examples": [
                          "Hi, I'm here to help!"
                        ]
                      }
                    }
                  }
                },
                "logprobs": {
                  "type": "number",
                  "nullable": true,
                  "examples": [
                    null
                  ]
                },
                "finish_reason": {
                  "type": "string",
                  "examples": [
                    "stop"
                  ]
                }
              }
            }
          },
          "usage": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "prompt_tokens": {
                  "type": "integer",
                  "examples": [
                    0
                  ]
                },
                "completion_tokens": {
                  "type": "integer",
                  "examples": [
                    0
                  ]
                },
                "total_tokens": {
                  "type": "integer",
                  "examples": [
                    0
                  ]
                }
              }
            }
          }
        }
      },
      "CompletionResponseStream": {
        "description": "Response of completion, where `stream=true`",
        "properties": {
          "id": {
            "type": "string",
            "description": "The id passed through `Authorization` header",
            "examples": [
              "voy-5uh12i196p8rqqgo3pbdmoaj1teit9clgk9ujkk0n91o"
            ]
          },
          "object": {
            "type": "string",
            "examples": [
              "chat.completion"
            ]
          },
          "created": {
            "type": "integer",
            "examples": [
              1722576434241
            ]
          },
          "model": {
            "type": "string",
            "examples": [
              "Phi3-mini-4k-instruct-Q4.gguf"
            ]
          },
          "system_fingerprint": {
            "type": "fp_2flh9v7kboo"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "delta": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "role": {
                        "type": "string",
                        "examples": [
                          "assistant"
                        ]
                      },
                      "content": {
                        "content": "string",
                        "examples": [
                          "Hi, "
                        ]
                      }
                    }
                  }
                },
                "logprobs": {
                  "type": "number",
                  "nullable": true,
                  "examples": [
                    null
                  ]
                },
                "finish_reason": {
                  "type": "string",
                  "examples": [
                    null,
                    "stop"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "api_key": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Please input your api key here. You can get it from GET /v1/token/api-key"
      }
    }
  }
}