Create a knowledge base entry | Sensay API documentation

Create a knowledge base entry Beta

POST /v1/replicas/{replicaUUID}/knowledge-base

Organization service token Organization service token & User

Creates a new knowledge base entry for a replica based on text, file, URL, or Youtube Videos. For YouTube playlists, the system will automatically create separate entries for each video in the playlist.

Headers

X-API-Version string

Default value is 2025-03-25.

Path parameters

replicaUUID string(uuid) Required

The replica unique identifier (UUID)

application/json

Body

title string

Title for this knowledge base entry. Helps identify the content in listings.
url string(uri)

A public URL to an HTML page to ingest into the knowledge base. The URL must be publicly accessible without authentication. Google domains(e.g. www.google.com, docs.google.com) are not allowed. Only the rendered text on the web page is used for training, embedded media (image, video, audio) is not used. For training using video files, please provide YouTube links in one of the following formats: https://www.youtube.com/watch?v=VIDEO_ID https://www.youtube.com/shorts/SHORT_VIDEO_ID https://www.youtube.com/playlist?list=PLAYLIST_ID

Format should match the following pattern: https?:\/\/[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z0-9()]+\b([-a-zA-Z0-9()@:%_+.~#?&\/=]*).
autoRefresh boolean

Whether to allow automatic content updates from the URL, handled by the system.

Default value is false.
text string

The text content you want your replica to learn

Minimum length is 1.
filename string
The name of the file that you intend to upload. Supported file types:
- Documents: .doc, .docx, .rtf, .pdf, .pdfa
- Spreadsheets and Tabular Data: .csv, .tsv, .xls, .xlsx, .xlsm, .xlsb, .ods, .dta, .sas7bdat, .xpt
- Presentations: .ppt, .pptx
- Text Files: .txt, .md, .htm, .html, .css, .js, .xml
- Data Text Files: .json, .yml, .yaml
- E-books: .epub
- Images: .png, .jpg, .jpeg, .webp, .heic, .heif, .tiff, .bmp
- Audio Files: .mp3, .wav, .aac, .ogg, .flac
- Video Files: .mp4, .mpeg, .mov, .avi, .mpg, .webm, .mkv (Maximum duration: 90 minutes)

Responses

207 application/json

The created knowledge base entry
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates if the knowledge base entry was created successfully
- results array[object] Required
  
  Array of results for each knowledge base entry created
  
  Any of:
  object-1 object object-2 object
  
  Hide attributes Show attributes
  
  type string Required
  
  The type of knowledge base entry
  
  Values are file, text, website, or youtube.
  
  enqueued boolean Required
  
  Indicates that the knowledge base entry creation has been enqueued for processing
  
  Value is true.
  
  knowledgeBaseID number Required
  
  The unique identifier for the newly created knowledge base entry.
  
  signedURL string
  
  The temporary URL where you should upload your file using a PUT request
  
  Hide attributes Show attributes
  
  type string Required
  
  The type of knowledge base entry
  
  Values are file, text, website, or youtube.
  
  enqueued boolean Required
  
  Indicates that the knowledge base entry creation has not been enqueued due to an error
  
  Value is false.
  
  error string Required
  
  Error message if the knowledge base entry creation failed
400 application/json

Bad Request
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- fingerprint string
  
  A unique identifier of the event, useful for reporting
- request_id string Required
  
  A unique identifier of the request, useful for reporting
401 application/json

Unauthorized
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- fingerprint string
  
  A unique identifier of the event, useful for reporting
- request_id string Required
  
  A unique identifier of the request, useful for reporting
404 application/json

Not Found
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- request_id string Required
  
  A unique identifier of the request, useful for reporting
409 application/json

URL already exists in the knowledge base
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- fingerprint string
  
  A unique identifier of the event, useful for reporting
- request_id string Required
  
  A unique identifier of the request, useful for reporting
415 application/json

Unsupported Media Type
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- fingerprint string
  
  A unique identifier of the event, useful for reporting
- request_id string Required
  
  A unique identifier of the request, useful for reporting
500 application/json

Internal Server Error
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- fingerprint string
  
  A unique identifier of the event, useful for reporting
- request_id string Required
  
  A unique identifier of the request, useful for reporting
- inner_exception object
  
  The inner exception
  
  Hide inner_exception attributes Show inner_exception attributes object
  
  name string Required
  
  message string Required
  
  cause string
  
  stack string

POST /v1/replicas/{replicaUUID}/knowledge-base

curl \
 --request POST 'https://api.sensay.io/v1/replicas/03db5651-cb61-4bdf-9ef0-89561f7c9c53/knowledge-base' \
 --header "X-ORGANIZATION-SECRET: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "X-API-Version: 2025-03-25" \
 --data '{"title":"Company information","url":"https://example.com","autoRefresh":false,"text":"Our company was founded in 2020. We specialize in AI-powered customer service solutions.","filename":"example.txt"}'

Request examples

# Headers
X-API-Version: 2025-03-25

# Payload
{
  "title": "Company information",
  "url": "https://example.com",
  "autoRefresh": false,
  "text": "Our company was founded in 2020. We specialize in AI-powered customer service solutions.",
  "filename": "example.txt"
}

Response examples (207)

{
  "success": true,
  "results": [
    {
      "type": "file",
      "enqueued": true,
      "knowledgeBaseID": 12345,
      "signedURL": "https://xotqxvmmnunwfsaemqfy.supabase.co/storage/v1/object/upload/sign/replica_files/..."
    }
  ]
}

Response examples (400)

{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}

Response examples (401)

{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}

Response examples (404)

{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}

Response examples (409)

{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}

Response examples (415)

{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}

Response examples (500)

{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b",
  "inner_exception": {
    "name": "Server overheated",
    "cause": "Request too complicated",
    "stack": "Error: Server overheated due to an unexpected situation\n    at Object.eval (eval at <anonymous>...",
    "message": "The server overheated due to an unexpected situation"
  }
}