# FileGPT API Documentation ## About this This is the official documentation of FileGPT. We will walk you through basics of using FileGPT API. As a quick intro, FileGPT () allows you to chat with all kinds of documents, including but not limited to, regular files, audios and videos, and youtube! We deliver a consistent experience and integration for a range of documents, types, and embeddings, trying to bring the service to ## Getting Started 1. First, log in on and go to your profile page. API access is available to our pro users and above. 2. Once you have access, you will be able to view your api usage on the profile page. You also have the options to generate api keys and invalidate old ones. 3. For all requests coming in at FileGPT, authentication is needed by setting\ `Authorization: `, for example `Authorization: abcdefgh` 4. Thats it! Easy peasy! ## API Endpoints **The base endpoint is `https://lb.filegpt.app`** Below is a sample workflow of using our API. We first present the existing endpoints and then show some working end-to-end examples to get you started easily. First, a collection is a set of documents. A document is the basic building block, and note that documents have different types. Generally, we categorize documents into three for now: 1. FILE: this is the most common one, it covers pdf, txt, pptx, jpg, etc. 2. YOUTUBE: this handles the youtube video links 3. WEB\_URL: this handles web pages
### `POST /api/collection` create a collection with a list of documents. You should pass in a [ApiCollectionCreateRequest](#apicollectioncreaterequest) object. ## create a collection with a list of documents. `POST` `ENDPOINT/api/collection` #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | -------------------------------------------------- | | title\* | String | | | documents\* | List | List of documents, see schema for detail reference | {% tabs %} {% tab title="200: OK A collection object. will be returned" %} {% endtab %} {% endtabs %} ### `GET /api/collection/{collection_id}` ## Get the collection `GET` `ENDPONIT/api/collection/{collection_id}` This will get the collection and all documents in the collection #### Path Parameters | Name | Type | Description | | ------------------------------------------------ | ------ | ----------- | | collection\_id\* | String | | {% tabs %} {% tab title="200: OK A collection object" %} {% endtab %} {% endtabs %} #### Return value A [collection](#collection-schema) object. ### `DELETE /api/collection/{collection_id}` This will delete all files in your collection for privacy and security. Recommended to use as often as possible. ## Get the collection `DELETE` `ENDPOINT/api/collection/{collection_id}` This will delete the collection and all documents in the collection #### Path Parameters | Name | Type | Description | | ------------------------------------------------ | ------ | ----------- | | collection\_id\* | String | | {% tabs %} {% tab title="200: OK A collection object" %} {% endtab %} {% endtabs %} #### Parameter your collection id #### Return Value A [collection](#collection-schema) object. ### `POST /api/build` ## Build and process the collection `POST` `http://ENDPOINT/api/api/build` #### Request Body | Name | Type | Description | | ---------------------------------------------- | ------ | ----------- | | collectionId\* | String | | {% tabs %} {% tab title="200: OK A collection object" %} {% endtab %} {% endtabs %} #### Parameter A [BuildRequest](#buildrequest) object. #### Return Value A success status of 200. Note that the build job is async. You should use the `GET` method to poll the status of the collection, and the status will change to `READY` if everything goes well, or it will be `FAILED` if error occured. The error message is in the StatusMessage field. ### POST /api/query #### Parameter Send a JSON body of a [#queryrequest](#queryrequest "mention") Object. #### Return Value A plain text streaming response. Non-streaming version will be out soon. We will provide examples on how to consume the stream if you need. ## End-to-End Example #### Example Building a Custom Chatbot with QA In this example, we walk through how you can use filegpt as an add-on service, on top of your existing chatbot, to let users chat with their own documents. Here's an outline of the workflow: 1. You manage your storage of users' uploaded file. 2. Generate a presigned URL with a 1-2 minute expiration window 3. Create a collection with the documents, you can create a collection with one or multiple documents. 4. Build the collection 5. Query the collection with the user input. ```python # s3, gcs, etc. Your file storage service. file_url = await generate_presigned_url() # create collection collection = await requests.post( 'ENDPOINT/api/collection', headers={'Authorization':'YOUR_API_KEY'}, data={ # Here is the collection information "title": "demo", "documents": [{ "name": "abc", "document_type": "FILE", "url": "https://www.africau.edu/images/default/sample.pdf" }] }) # build collection await requests.post( 'ENDPOINT/api/collection', headers={'Authorization':'YOUR_API_KEY'}, data={ 'collectionId': collection.id } ) # query collection with Stream query_data = { "collectionId": "457cd51f-662c-4ab5-9fb7-949ea031de2f", "query": "summarize the doc", "mode": "default", "messageHistory":[ { "content": "my name is alex", "author": "bot" } ] } response = requests.post('ENDPOINT/api/query', data=query_data, stream=True) result = "" # Ensure the request was successful if response.status_code == 200: # Consume the stream for chunk in response.iter_content(chunk_size=1024): if chunk: # filter out keep-alive new chunks print(chunk) result += chunk else: print("Error:", response.status_code, response.text) ``` ## Appendix ### ApiCollectionCreateRequest This is the object you need to create a a collection. You specify a list of documents of your own, with URL provided, and then you can create a collection. It holds all documents together. ```python class ApiCollectionCreateRequest(): title: string documents: Array[ApiDocument] class ApiDocument(): """ name: name of the document document_type: resource type url: link to the resource """ name: string document_type: 'FILE' | 'YOUTUBE_URL' | 'WEB_URL' url: string ### Example { "title": "demo", "documents": [{ "name": "abc", "document_type": "FILE", "url": "https://www.africau.edu/images/default/sample.pdf" }] } ``` ### BuildRequest ```python class BuildRequest(): collectionId: str ### Example { "collectionId": "abcd" } ``` ### QueryRequest ```python class QueryRequest(): query: str collectionId: str chatModel: Optional[str] = "gpt-3.5-turbo" | "gpt-4" messageHistory: Optional[List[ApiChatMessage]] = [] class ApiChatMessageAuthor(Enum): BOT = "bot" USER = "user" class ApiChatMessage(): content: str author: ApiChatMessageAuthor ### Example { "query": "what is my name?", "collectionId": "abcd", "messageHistory": [ { "author": "user", "content": "my name is alex." } ] } ``` ### Collection Schema {% code fullWidth="false" %} ```python class Collection(): """Represents a Collection record""" id: _str title: _str status: 'NOT_STRATED' | 'BUILDING' | 'READY' | 'FAILED' createdAt: datetime.datetime updatedAt: datetime.datetime statusMessage: Optional[str] documents: Optional[List[Document]] ### Example { "id": "abcdefghijklmn", "title": "demo", "status": "READY", "createdAt": "2023-05-13T01:39:01.106000+00:00", "updatedAt": "2023-05-13T01:39:40.452000+00:00", "userId": "abcdefghijklmn", "statusMessage": "collection is ready", "documents": [ { "id": "abcdefghijklmn", "name": "abc", "URL": "https://www.africau.edu/images/default/sample.pdf", "createdAt": "2023-05-13T01:39:01.106000+00:00", "updatedAt": "2023-05-13T01:39:01.106000+00:00", "type": "FILE", "collections": null } ] } ``` {% endcode %}