Playground Videos Blog Pricing

Knowledge Bank API

All the relevant APIs needed to interact with Knowledge Bank for you AI characters with Convai.

Upload a new KB File

POST https://api.convai.com/character/knowledge-bank/upload

Users can upload a new KB file. Once the file is successfully uploaded, they can connect it to a character. Upon calling the API, the file will only be uploaded for processing and will not be available for use until the processing is complete. The upload API will return a unique ID assigned to the uploaded file, which must be used for all future interactions with the file.

Headers

NameTypeDescription

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

NameTypeDescription

file_name

String

Name of the file

file

Bytes

Raw file bytes

{
   "id": "<uuid of the uploaded file>",
   "file_name": "<file_name>",
   "is_available": false,
   "status": "inactive",
   "timestamp": "2024-09-17 20:51:09.216522",
   "file_size": "72374"
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/knowledge-bank/upload"


headers = { 
  'CONVAI-API-KEY': '<Your-API-Key>',
}

# Path to the file you want to upload
file_path = "photosynthesis.txt"

# Open the file in binary mode
with open(file_path, "rb") as file:
    # Create a dictionary for the form data
    form_data = { 
        "file_name": file.name,
        "file": file
    }   

    # Send the POST request with multipart/form-data
    response = requests.post(url, headers=headers, files=form_data)


print(response.text)

List KB File Status

POST https://api.convai.com/character/knowledge-bank/list

List the status of KB files. Use this API to check the status of previously uploaded KB files. Once this API returns "is_available" as true for your UUID, you can confidently assume that the previously uploaded file is processed and ready to be connected to your character.

Please note that the list API requires the character_id as input. Accordingly, it returns a "status" field, which can either be "active" or "inactive." This field indicates whether a particular file is connected to a character. A file is considered connected if its "status" is "active" in the output.

Headers

NameTypeDescription

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

NameTypeDescription

character_id

String

Id of your character.

{
  'docs': [
    '{
        "id": "<File UUID>",
        "file_name": "photosynthesis.txt",
        "is_available": true,
        "status": "inactive",
        "timestamp": "2024-09-17 21:44:53.201385",
        "file_size": "1404"
    }',
    '{
        "id": "<File UUID>",
        "file_name": "FAQ.txt",
        "is_available": true,
        "status": "inactive",
        "timestamp": "2024-09-17 21:21:35.566677",
        "file_size": "736"
    }']
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/knowledge-bank/list"


headers = { 
  'CONVAI-API-KEY': '<Your-API-Key>',
}

# Create a dictionary for the form data
form_data = { 
    'character_id': '<Your-CharacterId>',
}

# Send the POST request with multipart/form-data
response = requests.post(url, headers=headers, data=form_data)

print(response.text)

Connect (or Disconnect) a KB file to a Character

POST https://api.convai.com/character/update

Update API can be used to attach (or remove) a KB file to your character. Once the file is successfully connected, all future interactions with the character will fetch knowledge from the attached KB as needed.

Headers

NameTypeDescription

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

NameTypeDescription

charID

String

Id of your character.

docs

List

List of JSON. Each entry correspond to a file. Fields "id" and "status".

{"STATUS": "SUCCESS"}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/update"

headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# Create a dictionary for the JSON payload
payload = { 
    "charID": "<Your-Character-Id>",
    "docs": [
        {   
            "id": "<File-UUID>",
            "status": "active"  # or "inactive" depending on what you want to set
        }   
    ]   
}

# Convert the payload to JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)
PreviousCharacter APINextAction API

Last updated