List all knowledge base entries | Sensay API documentation

List all knowledge base entries Beta

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

Returns a list of all knowledge base entries belonging to a replica. This endpoint allows you to view all your training data in one place, with optional filtering by status or type. You can use this to monitor the overall state of a replica's knowledge base, check which entries are still processing, and identify any that might have encountered errors. The response includes detailed information about each entry including its content, status, and metadata.

Headers

X-API-Version string

Default value is 2025-03-25.

Path parameters

replicaUUID string(uuid) Required

The replica unique identifier (UUID)

Query parameters

status array[string] | null

Filter knowledge base entries by comma separated list of their processing statuses. Use this to find entries in specific states like NEW or READY.

Values are NEW, FILE_UPLOADED, RAW_TEXT, PROCESSED_TEXT, VECTOR_CREATED, READY, or UNPROCESSABLE.
type array[string] | null

Filter knowledge base entries by their content type. Use this to find specific types of training data like text or file uploads.

Values are file, text, website, or youtube.
search string

Filter knowledge base entries by their title, filename, or URL.

Minimum length is 3.
hasError string

Filter knowledge base entries that have encountered errors during processing.

Values are true or false.
page integer

Page number for pagination. Use this to navigate through large result sets.

Default value is 1.
pageSize integer | null

Maximum number of entries to return per page (up to 100). Use this to control result set size. A value of zero can be used to check the total number of items without returning any items.

Minimum value is 0, maximum value is 100. Default value is 24.
sortBy string

Sort criteria.

Value is createdAt. Default value is createdAt.
sortOrder string

The order of the sort.

Values are asc or desc. Default value is desc.

Responses

200 application/json

List of knowledge base entries returned successfully.
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates if the list operation was successful
- items array[object] Required
  
  Array of knowledge base entries matching your query parameters
  
  Hide items attributes Show items attributes object
  
  id integer Required
  
  The unique identifier for this knowledge base entry.
  
  replicaUUID string(uuid)
  
  The unique identifier of the replica associated to this knowledge base entry.
  
  type string Required
  
  The type of knowledge base entry, indicating how the content was added and how it should be processed.
  
  Values are file, text, website, or youtube.
  
  url string
  
  The URL provided during entry creation, if applicable.
  
  status string Required
  
  The current stage in the processing pipeline. Use this to track progress and identify any issues with processing.
  
  Values are NEW, FILE_UPLOADED, RAW_TEXT, PROCESSED_TEXT, VECTOR_CREATED, READY, or UNPROCESSABLE.
  
  createdAt string(date-time) Required
  
  The ISO 8601 timestamp indicating when this knowledge base entry was created.
  
  updatedAt string(date-time) Required
  
  The ISO 8601 timestamp indicating when this knowledge base entry was last updated. Useful for tracking the completion time of processing.
  
  title string
  
  Title for the knowledge base entry, to help identify the knowledge base entry in listings. This field is not used in processing or internal logic.
  
  generatedTitle string
  
  Auto-generated title for the knowledge base entry based on the content.
  
  summary string
  
  A concise 1-2 sentence summary of rawText, generated by the system.
  
  website object
  
  Website content related to the knowledge base entry
  
  Additional properties are NOT allowed.
  
  Hide website attributes Show website attributes object
  
  url string(uri) Required
  
  URL of the website related to the knowledge base entry.
  
  links array[string]
  
  Links related to the knowledge base entry.
  
  title string
  
  Title of the website.
  
  text string
  
  Text content of the website.
  
  description string
  
  A brief description of the website content based on extracted html.
  
  autoRefresh boolean
  
  Whether to allow automatic content updates from the URL, handled by the system.
  
  Default value is false.
  
  screenshotURL string
  
  Screenshot URL of the knowledge base entry.
  
  youtube object
  
  YouTube content related to the knowledge base entry
  
  Additional properties are NOT allowed.
  
  Hide youtube attributes Show youtube attributes object
  
  url string(uri) Required
  
  URL of the YouTube video related to the knowledge base entry
  
  title string
  
  Title of the YouTube video
  
  description string
  
  Description of the YouTube video
  
  thumbnailURL string(uri)
  
  URL of the YouTube video thumbnail
  
  summary string
  
  A concise 1-2 sentence summary of rawText.
  
  transcription string
  
  Full transcript of the YouTube video.
  
  visualTranscription string
  
  Visual transcription of the YouTube video
  
  playlistID string
  
  ID of the YouTube playlist associated with this knowledge base entry
  
  file object
  
  File content related to the knowledge base entry
  
  Additional properties are NOT allowed.
  
  Hide file attributes Show file attributes object
  
  name string Required
  
  Name of the file associated with the knowledge base entry
  
  size number | null
  
  Size of the file in bytes
  
  mimeType string | null
  
  MIME type of the file
  
  Values are application/epub+zip, application/json, application/msword, application/pdf, application/rtf, application/vnd.ms-excel, application/vnd.ms-excel.sheet.binary.macroenabled.12, application/vnd.ms-excel.sheet.macroEnabled.12, application/vnd.ms-powerpoint, application/vnd.oasis.opendocument.spreadsheet, application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/x-sas-data, application/x-sas-xport, application/x-stata, application/x-stata-dta, application/yaml, audio/aac, audio/flac, audio/mp3, audio/mpeg, audio/ogg, audio/wav, image/bmp, image/heic, image/heif, image/jpeg, image/png, image/tif, image/tiff, image/webp, text/css, text/csv, text/html, text/javascript, text/markdown, text/plain, text/tab-separated-values, text/xml, video/avi, video/mov, video/mp4, video/mpeg, video/mpg, video/webm, or video/x-matroska.
  
  screenshotURL string
  
  Screenshot URL of the knowledge base entry.
  
  downloadURL string(uri)
  
  Temporary signed URL for downloading the file
  
  error object
  
  Error information related to the knowledge base entry
  
  Additional properties are NOT allowed.
  
  Hide error attributes Show error attributes object
  
  fingerprint string
  
  A unique identifier of the error, useful for reporting
  
  message string
  
  Error message associated with this knowledge base entry
- total integer Required
  
  The total number of knowledge base entries.
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
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

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

curl \
 --request GET 'https://api.sensay.io/v1/replicas/03db5651-cb61-4bdf-9ef0-89561f7c9c53/knowledge-base' \
 --header "X-API-Version: 2025-03-25"

Response examples (200)

{
  "success": true,
  "items": [
    {
      "id": 12345,
      "type": "text",
      "title": "Company information",
      "status": "READY",
      "summary": "Basic company details and policies",
      "createdAt": "2025-04-15T08:11:00.093761+00:00",
      "updatedAt": "2025-04-15T08:11:05.299349+00:00",
      "replicaUUID": "03db5651-cb61-4bdf-9ef0-89561f7c9c53"
    }
  ],
  "total": 100
}

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 (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"
  }
}