LogoLogo
PlaygroundVideosBlogPricing
  • Welcome
  • Convai Playground
    • Playground Walkthrough
    • Get Started
    • Character Creator Tool
      • Create Character
      • Language and Speech
      • Knowledge Bank
      • Personality and Style
      • State of Mind
      • Memory
      • Actions
      • Narrative Design
      • Character Versioning
    • F.A.Q
  • Plugins & Integrations
    • Introduction
    • Unity Plugin
      • Pre-Requisites
      • Compatibility
      • Downloads
        • Limitations of WebGL Plugin
      • Setting Up Unity Plugin
      • Troubleshooting Guide
        • Disable Assembly Validation
        • Missing Newtonsoft Json
        • Microphone Permission Issues
        • Default Animations Incompatibility
        • Animations have Facial Blendshapes
        • Jaw Bone in Avatar is not Free
        • macOS Permission Issues
      • Creating a Convai Powered Scene from Template
      • Importing Ready Player Me (RPM) Characters
      • Importing Custom Characters
      • Adding Actions to your Character
      • Adding Lip-Sync to your Character
      • Adding Narrative Design to your Character
        • Narrative Design Keys
      • Adding NPC to NPC Conversation
      • Adding Scene Reference and Point-At Crosshairs
      • Utilities
        • Character Emotion
        • Player Data Container
        • Long Term Memory
        • Language Support
        • Managing sessionID Locally
        • Transcript UI System
        • Pre-built UI Prefabs
        • Input Management
        • Notification System
        • Settings Panel
        • Dynamic Information Context
      • Building For Supported Platforms
        • Building for iOS/iPadOS
        • Building for WebGL
        • Convai XR
          • Building for VR
            • VR Automatic Installation
            • VR Manual Installation
          • Building for MR
            • MR Automatic Installation
            • MR Manual Installation
          • Building for AR
          • Interacting with XR UI Elements
        • Building for macOS Universal apps
      • Changelogs
      • Tutorials
        • Narrative Design
        • NPC2NPC
    • Unreal Engine
      • Supported Platforms
      • Installation
      • Guides
        • Dynamic Environment Info
        • Change AI Character Movement Speed
        • Integration with Pixel Streaming
        • Adjust Interaction Radius
        • Creating MetaHuman Characters
          • Adding MetaHuman
          • Adding LipSync to MetaHuman (From plugin version 3.0.0 or later )
          • Change the Parent Class for MetaHuman
          • Change the parent class for Player.
          • Adding LipSync to MetaHuman (Deprecated)
        • Creating ReadyPlayerMe Characters
          • Download Plugins
          • Adding ReadyPlayerMe Character
          • Change the parent class for Player.
        • Creating Reallusion Characters
          • Creating a Reallusion Character
          • Importing Reallusion character and setting up the Convai plugin
          • Binding objects to Reallusion Character
        • Event-Aware Convai Characters
        • Operations Based on the Presence of Certain Words
        • Narrative Design
          • Narrative Design Trigger
          • Narrative Design Keys
        • Actions Guide
          • Stage 1: Default Actions
            • Moves To
            • Follows
          • Stage 2: Custom Actions
            • Simple actions
            • Adding Descriptions to Actions
          • Stage 3: Custom Actions with Single Parameter
          • Main Character and Attention Object
        • Customization
          • Push to Talk
          • Alter Character Response Audio Rate
        • Speech To Text Transcription
        • Enable Multiplayer Support
        • 3D Chat Widget
        • Long Term Memory
        • Saving and Loading Session
      • Blueprints Reference
        • Convai Player
        • Convai Chatbot
        • Convai Environment
        • Convai Object Entry
        • Convai Result Action
        • Convai Extra Params
        • Speech To Text
        • Text To Speech
        • Utility Functions
      • Troubleshoot Guide
        • Missing Unreal Engine Tool Set in Microsoft Visual Studio Toolchain
        • Convai Module Not Found
        • MetaHuman Plugin Conflict
        • Failure to Load Character IDs
      • Microphone Settings
        • Set Audio Gain
        • Set Microphone
        • Microphone test
        • List Microphone Devices
      • Mac Microphone Permission: Required for UE 5.0 and 5.3
      • Guides V2 (Under Development)
        • Getting Started
          • Installation
          • Simple Talking Cube
          • Adding Premade Chat and Settings UI
    • Web Plugin
      • PlayCanvas Plugin
        • Adding External Script
        • First Person View
        • Adding characters to scene
        • Character Animations
        • Convai Integration
        • Chat Overlay
      • Convai Web SDK
        • Getting Started
        • Facial Expressions
        • Actions
      • JavaScript Chat UI SDK
        • Getting Started
        • ChatBubble Props
      • Narrative Design Guide
        • Narrative Design Triggers
        • Narrative Design Keys
      • GLB Characters for Convai
      • GLB/FBX animations for Convai
    • Modding Framework
      • Modding Cyberpunk 2077
    • Other Integrations
      • Roblox
        • Sample Game 1
        • Sample Game 2
        • Code Example
          • Character Conversation API
      • Discord
        • Create a Discord Bot
        • Hosting Discord Bot from Personal Server
        • Hosting Discord Bot from Replit
      • Omniverse Extension
      • Third-Party API Integrations
        • ElevenLabs API Integration
    • Convai Pixel Streaming Embed
      • Whitelisting & Publishing an Experience
      • React Typescript
      • ReactJS (JavaScript)
      • Vanilla JavaScript (ES Modules)
      • CDN (UMD Script)
      • On Premise Deployment
      • API Reference
  • Reference
    • Core API Reference
      • Character Base API
      • Interaction API
      • Core AI Setting API
      • Backstory API
      • Chat History API
      • Knowledge Bank API
      • Narrative Design API
      • Action API
      • Language List API
      • Voice List API
      • Character List API
      • Evaluation API
Powered by GitBook
On this page
  • Upload a new KB File
  • Update Existing KB File
  • List KB File Status
  • Connect (or Disconnect) a KB file to a Character
  • Delete a KB file

Was this helpful?

  1. Reference
  2. Core API Reference

Knowledge Bank API

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

This API is accessible only with the Enterprise plan.

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

Name
Type
Description

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

Name
Type
Description

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"
}
{
    "API_ERROR": "Invalid API key provided.
}

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)
curl -X POST \
  https://api.convai.com/character/knowledge-bank/upload \
  -H 'CONVAI-API-KEY: <Your-API-Key>' \
  -F 'file_name=photosynthesis.txt' \
  -F 'file=@photosynthesis.txt'

Update Existing KB File

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

Users can update an existing KB file by uploading a new version. 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.

Headers

Name
Type
Description

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

Name
Type
Description

document_id

String

ID of the existing document that needs to be upated

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"
}
{
    "API_ERROR": "Invalid API key provided.
}

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/update"


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
    files = {"file": ("photosynthesis-filename.txt", file, "text/plain")}
    form_data = {"document_id": "<document_id"}

    # Send the POST request with multipart/form-data
    response = requests.post(url, headers=headers, files=files, data=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

Name
Type
Description

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

Name
Type
Description

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"
    }']
}
{
    "API_ERROR": "Invalid API key provided.
}

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)
curl -X POST 'https://api.convai.com/character/knowledge-bank/list' \
  -H 'CONVAI-API-KEY: <Your-API-Key>' \
  -F 'character_id=<Your-CharacterId>'

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

Name
Type
Description

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

Name
Type
Description

charID

String

Id of your character.

docs

List

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

{"STATUS": "SUCCESS"}
{
    "API_ERROR": "Invalid API key provided.
}

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)
curl -X POST 'https://api.convai.com/character/update' \
-H 'CONVAI-API-KEY: <Your-API-Key>' \
-H 'Content-Type: application/json' \
-d '{
  "charID": "<Your-Character-Id>",
  "docs": [
    {
      "id": "<File-UUID>",
      "status": "active"
    }
  ]
}'

Delete a KB file

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

The knowledge bank delete API can be used to permanently remove documents from the user's account. Note that deleting a document will remove it from all characters it is associated with.

Headers

Name
Type
Description

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

Name
Type
Description

document_id

String

Id of the document that should be deleted.

{"Successfully deleted document"}
{
    "API_ERROR": "Invalid API key provided.
}

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/delete"

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

# Create a dictionary for the JSON payload
form_data = { 
    "document_id": "<File-UUID>"   
}

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

print(response.text)
curl -X POST "https://api.convai.com/character/knowledge-bank/delete" \
-H "CONVAI-API-KEY: <Your-API-Key>" \
-d "document_id=<File-UUID>"
PreviousChat History APINextNarrative Design API

Last updated 2 months ago

Was this helpful?