{
  "openapi": "3.1.0",
  "info": {
    "title": "Dewy Knowledge Base API",
    "summary": "Knowledge curation for Retrieval Augmented Generation",
    "description": "This API allows ingesting and retrieving knowledge.\n\nKnowledge comes in a variety of forms -- text, image, tables, etc. and\nfrom a variety of sources -- documents, web pages, audio, etc.",
    "version": "0.4.0"
  },
  "servers": [
    {
      "url": "http://localhost:8000",
      "description": "Local server"
    }
  ],
  "paths": {
    "/api/chunks/": {
      "get": {
        "tags": [
          "kb"
        ],
        "summary": "List Chunks",
        "description": "List chunks.",
        "operationId": "listChunks",
        "parameters": [
          {
            "name": "collection",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Limit to chunks associated with this collection",
              "title": "Collection"
            },
            "description": "Limit to chunks associated with this collection"
          },
          {
            "name": "document_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Limit to chunks associated with this document",
              "title": "Document Id"
            },
            "description": "Limit to chunks associated with this document"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Page number to fetch. The first page of results is page 1",
              "default": 1,
              "title": "Page"
            },
            "description": "Page number to fetch. The first page of results is page 1"
          },
          {
            "name": "perPage",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": 10,
              "title": "Perpage"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "oneOf": [
                      {
                        "$ref": "#/components/schemas/TextChunk"
                      },
                      {
                        "$ref": "#/components/schemas/ImageChunk"
                      }
                    ],
                    "discriminator": {
                      "propertyName": "kind",
                      "mapping": {
                        "text": "#/components/schemas/TextChunk",
                        "image": "#/components/schemas/ImageChunk"
                      }
                    }
                  },
                  "title": "Response Listchunks"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/chunks/{id}": {
      "get": {
        "tags": [
          "kb"
        ],
        "summary": "Get Chunk",
        "operationId": "getChunk",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "description": "The chunk ID.",
              "title": "Id"
            },
            "description": "The chunk ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/TextChunk"
                    },
                    {
                      "$ref": "#/components/schemas/ImageChunk"
                    }
                  ],
                  "discriminator": {
                    "propertyName": "kind",
                    "mapping": {
                      "text": "#/components/schemas/TextChunk",
                      "image": "#/components/schemas/ImageChunk"
                    }
                  },
                  "title": "Response Getchunk"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/chunks/retrieve": {
      "post": {
        "tags": [
          "kb"
        ],
        "summary": "Retrieve Chunks",
        "description": "Retrieve chunks based on a given query.",
        "operationId": "retrieveChunks",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetrieveRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RetrievedChunks"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/collections/": {
      "get": {
        "tags": [
          "kb"
        ],
        "summary": "List Collections",
        "description": "List collections.",
        "operationId": "listCollections",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Collection"
                  },
                  "type": "array",
                  "title": "Response Listcollections"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "kb"
        ],
        "summary": "Add Collection",
        "description": "Create a collection.",
        "operationId": "addCollection",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Collection"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Collection"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/collections/{name}": {
      "get": {
        "tags": [
          "kb"
        ],
        "summary": "Get Collection",
        "description": "Get a specific collection.",
        "operationId": "getCollection",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "The collection name.",
              "title": "Name"
            },
            "description": "The collection name."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Collection"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "kb"
        ],
        "summary": "Delete Collection",
        "description": "Delete a collection and all documents contained within it.",
        "operationId": "deleteCollection",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "The collection name.",
              "title": "Name"
            },
            "description": "The collection name."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Collection"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/documents/": {
      "post": {
        "tags": [
          "kb"
        ],
        "summary": "Add Document",
        "description": "Add a document to a collection.",
        "operationId": "addDocument",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddDocumentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "kb"
        ],
        "summary": "List Documents",
        "description": "List documents.",
        "operationId": "listDocuments",
        "parameters": [
          {
            "name": "collection",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Limit to documents associated with this collection",
              "title": "Collection"
            },
            "description": "Limit to documents associated with this collection"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Document"
                  },
                  "title": "Response Listdocuments"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/documents/{document_id}/content": {
      "post": {
        "tags": [
          "kb"
        ],
        "summary": "Upload Document Content",
        "description": "Add a document from specific content.",
        "operationId": "uploadDocumentContent",
        "parameters": [
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "description": "The collection to add the document to.",
              "title": "Document Id"
            },
            "description": "The collection to add the document to."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_uploadDocumentContent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/documents/{id}": {
      "get": {
        "tags": [
          "kb"
        ],
        "summary": "Get Document",
        "operationId": "getDocument",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "description": "The document ID.",
              "title": "Id"
            },
            "description": "The document ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "kb"
        ],
        "summary": "Delete Document",
        "description": "Delete a document.",
        "operationId": "deleteDocument",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "description": "The document ID.",
              "title": "Id"
            },
            "description": "The document ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/documents/{id}/status": {
      "get": {
        "tags": [
          "kb"
        ],
        "summary": "Get Document Status",
        "operationId": "getDocumentStatus",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "description": "The document ID.",
              "title": "Id"
            },
            "description": "The document ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AddDocumentRequest": {
        "properties": {
          "collection": {
            "type": "string",
            "title": "Collection",
            "examples": [
              "main"
            ]
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Url"
          }
        },
        "type": "object",
        "required": [
          "collection"
        ],
        "title": "AddDocumentRequest"
      },
      "Body_uploadDocumentContent": {
        "properties": {
          "content": {
            "type": "string",
            "format": "binary",
            "title": "Content",
            "description": "The document content."
          }
        },
        "type": "object",
        "required": [
          "content"
        ],
        "title": "Body_uploadDocumentContent"
      },
      "Collection": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name",
            "examples": [
              "my_collection"
            ]
          },
          "text_embedding_model": {
            "type": "string",
            "title": "Text Embedding Model",
            "default": "openai:text-embedding-ada-002",
            "examples": [
              "openai:text-embedding-ada-002",
              "hf:BAAI/bge-small-en"
            ]
          },
          "text_distance_metric": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DistanceMetric"
              }
            ],
            "default": "cosine"
          }
        },
        "type": "object",
        "required": [
          "name"
        ],
        "title": "Collection",
        "description": "A collection of indexed documents."
      },
      "DistanceMetric": {
        "type": "string",
        "enum": [
          "cosine",
          "ip",
          "l2"
        ],
        "title": "DistanceMetric"
      },
      "Document": {
        "properties": {
          "id": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Id"
          },
          "collection": {
            "type": "string",
            "title": "Collection"
          },
          "extracted_text": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Extracted Text"
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Url"
          },
          "ingest_state": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/IngestState"
              },
              {
                "type": "null"
              }
            ]
          },
          "ingest_error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Ingest Error"
          }
        },
        "type": "object",
        "required": [
          "collection"
        ],
        "title": "Document",
        "description": "Model for documents in Dewy."
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "ImageChunk": {
        "properties": {
          "id": {
            "type": "integer",
            "title": "Id"
          },
          "document_id": {
            "type": "integer",
            "title": "Document Id"
          },
          "kind": {
            "const": "image",
            "title": "Kind",
            "default": "image"
          },
          "image": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Image",
            "description": "Image of the node."
          },
          "image_mimetype": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Image Mimetype",
            "description": "Mimetype of the image."
          },
          "image_path": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Image Path",
            "description": "Path of the image."
          },
          "image_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Image Url",
            "description": "URL of the image."
          }
        },
        "type": "object",
        "required": [
          "id",
          "document_id",
          "image",
          "image_mimetype",
          "image_path",
          "image_url"
        ],
        "title": "ImageChunk"
      },
      "IngestState": {
        "type": "string",
        "enum": [
          "pending",
          "ingested",
          "failed"
        ],
        "title": "IngestState"
      },
      "RetrieveRequest": {
        "properties": {
          "collection": {
            "type": "string",
            "title": "Collection"
          },
          "query": {
            "type": "string",
            "title": "Query"
          },
          "n": {
            "type": "integer",
            "title": "N",
            "default": 10
          },
          "include_text_chunks": {
            "type": "boolean",
            "title": "Include Text Chunks",
            "default": true
          },
          "include_image_chunks": {
            "type": "boolean",
            "title": "Include Image Chunks",
            "default": true
          },
          "include_summary": {
            "type": "boolean",
            "title": "Include Summary",
            "default": false
          }
        },
        "type": "object",
        "required": [
          "collection",
          "query"
        ],
        "title": "RetrieveRequest",
        "description": "A request for retrieving chunks from a collection."
      },
      "RetrievedChunks": {
        "properties": {
          "summary": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Summary"
          },
          "text_chunks": {
            "items": {
              "$ref": "#/components/schemas/TextChunk"
            },
            "type": "array",
            "title": "Text Chunks",
            "default": []
          },
          "image_chunks": {
            "items": {
              "$ref": "#/components/schemas/ImageChunk"
            },
            "type": "array",
            "title": "Image Chunks",
            "default": []
          }
        },
        "type": "object",
        "title": "RetrievedChunks",
        "description": "The response from a retrieval request."
      },
      "TextChunk": {
        "properties": {
          "kind": {
            "const": "text",
            "title": "Kind",
            "default": "text"
          },
          "id": {
            "type": "integer",
            "title": "Id"
          },
          "document_id": {
            "type": "integer",
            "title": "Document Id"
          },
          "score": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Score"
          },
          "text": {
            "type": "string",
            "title": "Text"
          },
          "raw": {
            "type": "boolean",
            "title": "Raw"
          },
          "start_char_idx": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Start Char Idx",
            "description": "Start char index of the chunk."
          },
          "end_char_idx": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "End Char Idx",
            "description": "End char index of the chunk."
          }
        },
        "type": "object",
        "required": [
          "id",
          "document_id",
          "text",
          "raw"
        ],
        "title": "TextChunk"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      }
    }
  }
}