> For the complete documentation index, see [llms.txt](https://docs.epic-ai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.epic-ai.com/api-dokumentation/ai-knowledge-sources.md).

# Ai Knowledge Sources

## Lists all knowledge sources for a chatbot

> \
> \
> \*\*Required Permission:\*\* \`chatbots.knowledge-source.list\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Ai knowledge-sources","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/ai/knowledge/sources":{"get":{"operationId":"AiKnowledgeSourceController_listKnowledgeSources[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"pageToken","required":false,"in":"query","description":"The date after which to filter sources. Only sources created after this date will be fetched.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"The limit for how many sources should be fetched.","schema":{"type":"number"}},{"name":"excludeChildren","required":false,"in":"query","description":"TODO","schema":{"type":"boolean"}},{"name":"parentId","required":true,"in":"query","schema":{"type":"string"}},{"name":"groupId","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of all knowledge sources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListKnowledgeSourcesResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Lists all knowledge sources for a chatbot","tags":["Ai knowledge-sources"],"description":"\n\n**Required Permission:** `chatbots.knowledge-source.list`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"ListKnowledgeSourcesResponseDto":{"type":"object","properties":{"sources":{"description":"A list of retrieved knowledge sources.","type":"array","items":{"$ref":"#/components/schemas/KnowledgeSourceDto"}},"error":{"type":"string","description":"Optional error message"},"pageToken":{"type":"string","description":"The date of the latest fetched source."}},"required":["sources","pageToken"]},"KnowledgeSourceDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the knowledge source."},"source":{"type":"string","description":"The url or filepath of the source."},"groupIds":{"description":"A list of group ID's that the source is used in.","type":"array","items":{"type":"string"}},"enabled":{"type":"boolean","description":"Indicates whether the knowledge source is enabled (true) or disabled (false)."},"isIndexing":{"type":"boolean","description":"Sets the indexing status of the source."},"created":{"type":"string","description":"Creation timestamp (ISO format)."},"type":{"description":"Sets the type of the source.\n\n- `0`: WEBSITE\n- `1`: PDF\n","allOf":[{"$ref":"#/components/schemas/KnowledgeSourceType"}]},"status":{"description":"Sets the status of the source.\n\n- `0`: PENDING\n- `1`: INDEXING\n- `2`: INDEXED\n- `3`: ERROR\n- `4`: DELETING","allOf":[{"$ref":"#/components/schemas/KnowledgeSourceStatus"}]},"name":{"type":"string","description":"Sets the name of the source."},"errorReason":{"type":"string","description":"The reason for the potential error."},"metadata":{"type":"object","description":"Additional custom metadata as key-value pairs.","additionalProperties":{"type":"string"}},"role":{"description":"Role of the source in a parent-child relationship.\n\n- `0`: PARENT\n- `1`: CHILD\n- `2`: STANDALONE","allOf":[{"$ref":"#/components/schemas/KnowledgeSourceRole"}]},"parentId":{"type":"string","description":"ID of the parent source if this source is a child."},"updated":{"type":"string","description":"Last updated timestamp (ISO format)."},"firecrawlJobData":{"description":"Firecrawl job data if the source was created via firecrawl.","allOf":[{"$ref":"#/components/schemas/KnowledgeSource_FirecrawlJobDataDto"}]},"firecrawlCrawlOptions":{"description":"Crawl options used when the source was crawled via firecrawl.","allOf":[{"$ref":"#/components/schemas/CrawlOptionsDto"}]},"pageChecksum":{"type":"string","description":"Checksum of the page content."},"autoRecrawl":{"type":"boolean","description":"Whether to automatically recrawl this source after a successful crawl."}},"required":["id","source","groupIds","enabled","isIndexing","created","type","status","name","metadata","role","updated"]},"KnowledgeSourceType":{"type":"number","enum":[0,1,2,-1],"description":"Sets the type of the source.\n\n- `0`: WEBSITE\n- `1`: PDF\n"},"KnowledgeSourceStatus":{"type":"number","enum":[0,1,2,3,4,-1],"description":"Sets the status of the source.\n\n- `0`: PENDING\n- `1`: INDEXING\n- `2`: INDEXED\n- `3`: ERROR\n- `4`: DELETING"},"KnowledgeSourceRole":{"type":"number","enum":[0,1,2,-1],"description":"Role of the source in a parent-child relationship.\n\n- `0`: PARENT\n- `1`: CHILD\n- `2`: STANDALONE"},"KnowledgeSource_FirecrawlJobDataDto":{"type":"object","properties":{"jobId":{"type":"string","description":"Firecrawl job ID."},"jobStarted":{"type":"string","description":"Timestamp when the firecrawl job started."},"pagesCrawled":{"type":"number","description":"Number of pages crawled so far."},"creditsUsed":{"type":"number","description":"Credits used by firecrawl so far."},"lastCrawlJobId":{"type":"string","description":"Firecrawl job ID of the last crawl job."},"lastCrawlStatus":{"description":"Status of the last crawl.","allOf":[{"$ref":"#/components/schemas/LastCrawlStatus"}]}}},"LastCrawlStatus":{"type":"number","enum":[0,1,-1],"description":"Status of the last crawl."},"CrawlOptionsDto":{"type":"object","properties":{"maxDepth":{"type":"number","minimum":1,"maximum":100,"description":"Maximum depth to crawl."},"limit":{"type":"number","minimum":1,"maximum":1000,"description":"Maximum number of pages to crawl."},"includePaths":{"description":"Regex patterns for including specific paths.","type":"array","items":{"type":"string"}},"excludePaths":{"description":"Regex patterns for excluding specific paths.","type":"array","items":{"type":"string"}}}}}}}
```

## Deletes a batch of knowledge sources.

> \
> \
> \*\*Required Permission:\*\* \`chatbots.knowledge-source.delete\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Ai knowledge-sources","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/ai/knowledge/sources":{"delete":{"operationId":"AiKnowledgeSourceController_deleteKnowledgeSourceBatch[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteKnowledgeSourceBatchRequestDto"}}}},"responses":{"200":{"description":"Deletion result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteKnowledgeSourceResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Deletes a batch of knowledge sources.","tags":["Ai knowledge-sources"],"description":"\n\n**Required Permission:** `chatbots.knowledge-source.delete`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"DeleteKnowledgeSourceBatchRequestDto":{"type":"object","properties":{"sourceIds":{"description":"A list of deleted source Id's.","type":"array","items":{"type":"string"}}},"required":["sourceIds"]},"DeleteKnowledgeSourceResponseDto":{"type":"object","properties":{"error":{"type":"string","description":"Optional error message."},"deleted":{"type":"boolean","description":"Indicates whether the deletion succeeded."}},"required":["deleted"]}}}}
```

## Retrieves a specific knowledge source

> \
> \
> \*\*Required Permission:\*\* \`chatbots.knowledge-source.get\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Ai knowledge-sources","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/ai/knowledge/sources/{sourceId}":{"get":{"operationId":"AiKnowledgeSourceController_getKnowledgeSource[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}},{"name":"sourceId","required":true,"in":"path","description":"The ID of the knowledge source to retrieve.","schema":{"type":"string"}}],"responses":{"200":{"description":"Knowledge source details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetKnowledgeSourceResponseDto"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Retrieves a specific knowledge source","tags":["Ai knowledge-sources"],"description":"\n\n**Required Permission:** `chatbots.knowledge-source.get`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"GetKnowledgeSourceResponseDto":{"type":"object","properties":{"source":{"description":"The retrieved knowledge source.","nullable":true,"allOf":[{"$ref":"#/components/schemas/KnowledgeSourceDto"}]},"error":{"type":"string","description":"Optional error message"},"chunksContent":{"description":"Content of the source split into chunks.","type":"array","items":{"type":"string"}}},"required":["source","chunksContent"]},"KnowledgeSourceDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the knowledge source."},"source":{"type":"string","description":"The url or filepath of the source."},"groupIds":{"description":"A list of group ID's that the source is used in.","type":"array","items":{"type":"string"}},"enabled":{"type":"boolean","description":"Indicates whether the knowledge source is enabled (true) or disabled (false)."},"isIndexing":{"type":"boolean","description":"Sets the indexing status of the source."},"created":{"type":"string","description":"Creation timestamp (ISO format)."},"type":{"description":"Sets the type of the source.\n\n- `0`: WEBSITE\n- `1`: PDF\n","allOf":[{"$ref":"#/components/schemas/KnowledgeSourceType"}]},"status":{"description":"Sets the status of the source.\n\n- `0`: PENDING\n- `1`: INDEXING\n- `2`: INDEXED\n- `3`: ERROR\n- `4`: DELETING","allOf":[{"$ref":"#/components/schemas/KnowledgeSourceStatus"}]},"name":{"type":"string","description":"Sets the name of the source."},"errorReason":{"type":"string","description":"The reason for the potential error."},"metadata":{"type":"object","description":"Additional custom metadata as key-value pairs.","additionalProperties":{"type":"string"}},"role":{"description":"Role of the source in a parent-child relationship.\n\n- `0`: PARENT\n- `1`: CHILD\n- `2`: STANDALONE","allOf":[{"$ref":"#/components/schemas/KnowledgeSourceRole"}]},"parentId":{"type":"string","description":"ID of the parent source if this source is a child."},"updated":{"type":"string","description":"Last updated timestamp (ISO format)."},"firecrawlJobData":{"description":"Firecrawl job data if the source was created via firecrawl.","allOf":[{"$ref":"#/components/schemas/KnowledgeSource_FirecrawlJobDataDto"}]},"firecrawlCrawlOptions":{"description":"Crawl options used when the source was crawled via firecrawl.","allOf":[{"$ref":"#/components/schemas/CrawlOptionsDto"}]},"pageChecksum":{"type":"string","description":"Checksum of the page content."},"autoRecrawl":{"type":"boolean","description":"Whether to automatically recrawl this source after a successful crawl."}},"required":["id","source","groupIds","enabled","isIndexing","created","type","status","name","metadata","role","updated"]},"KnowledgeSourceType":{"type":"number","enum":[0,1,2,-1],"description":"Sets the type of the source.\n\n- `0`: WEBSITE\n- `1`: PDF\n"},"KnowledgeSourceStatus":{"type":"number","enum":[0,1,2,3,4,-1],"description":"Sets the status of the source.\n\n- `0`: PENDING\n- `1`: INDEXING\n- `2`: INDEXED\n- `3`: ERROR\n- `4`: DELETING"},"KnowledgeSourceRole":{"type":"number","enum":[0,1,2,-1],"description":"Role of the source in a parent-child relationship.\n\n- `0`: PARENT\n- `1`: CHILD\n- `2`: STANDALONE"},"KnowledgeSource_FirecrawlJobDataDto":{"type":"object","properties":{"jobId":{"type":"string","description":"Firecrawl job ID."},"jobStarted":{"type":"string","description":"Timestamp when the firecrawl job started."},"pagesCrawled":{"type":"number","description":"Number of pages crawled so far."},"creditsUsed":{"type":"number","description":"Credits used by firecrawl so far."},"lastCrawlJobId":{"type":"string","description":"Firecrawl job ID of the last crawl job."},"lastCrawlStatus":{"description":"Status of the last crawl.","allOf":[{"$ref":"#/components/schemas/LastCrawlStatus"}]}}},"LastCrawlStatus":{"type":"number","enum":[0,1,-1],"description":"Status of the last crawl."},"CrawlOptionsDto":{"type":"object","properties":{"maxDepth":{"type":"number","minimum":1,"maximum":100,"description":"Maximum depth to crawl."},"limit":{"type":"number","minimum":1,"maximum":1000,"description":"Maximum number of pages to crawl."},"includePaths":{"description":"Regex patterns for including specific paths.","type":"array","items":{"type":"string"}},"excludePaths":{"description":"Regex patterns for excluding specific paths.","type":"array","items":{"type":"string"}}}}}}}
```

## Crawl a website URL to create knowledge sources.

> \
> \
> \*\*Required Permission:\*\* \`chatbots.knowledge-source.create\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Ai knowledge-sources","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/ai/knowledge/sources/crawl":{"post":{"operationId":"AiKnowledgeSourceController_crawlKnowledgeSourceFromUrl[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrawlKnowledgeSourceFromUrlRequestDto"}}}},"responses":{"201":{"description":"The crawl job was started successfully."}},"summary":"Crawl a website URL to create knowledge sources.","tags":["Ai knowledge-sources"],"description":"\n\n**Required Permission:** `chatbots.knowledge-source.create`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"CrawlKnowledgeSourceFromUrlRequestDto":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The URL to crawl."},"options":{"description":"Crawl configuration options.","allOf":[{"$ref":"#/components/schemas/CrawlOptionsDto"}]}},"required":["url","options"]},"CrawlOptionsDto":{"type":"object","properties":{"maxDepth":{"type":"number","minimum":1,"maximum":100,"description":"Maximum depth to crawl."},"limit":{"type":"number","minimum":1,"maximum":1000,"description":"Maximum number of pages to crawl."},"includePaths":{"description":"Regex patterns for including specific paths.","type":"array","items":{"type":"string"}},"excludePaths":{"description":"Regex patterns for excluding specific paths.","type":"array","items":{"type":"string"}}}}}}}
```

## Uploads knowledge source files.

> \
> \
> \*\*Required Permission:\*\* \`chatbots.knowledge-source.create\`\
> \
> \*\*Resource:\*\* \`chatbots/:chatbotId\`

```json
{"openapi":"3.0.0","info":{"title":"ChatCaptain API","version":"1.0"},"tags":[{"name":"Ai knowledge-sources","description":""}],"servers":[{"url":"https://api.chatcaptain.com","description":"Production"}],"security":[{},{}],"paths":{"/v1/chatbots/{chatbotId}/ai/knowledge/sources/upload":{"post":{"operationId":"AiKnowledgeSourceController_uploadKnowledgeSourceFile[1]_v1","parameters":[{"name":"chatbotId","required":true,"in":"path","description":"The ID of the chatbot.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Files to be uploaded as knowledge sources.","content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadFilesDto"}}}},"responses":{"200":{"description":"Upload result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadKnowledgeSourceFilesResponseDto"}}}},"201":{"description":"","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Insufficient permissions."}},"summary":"Uploads knowledge source files.","tags":["Ai knowledge-sources"],"description":"\n\n**Required Permission:** `chatbots.knowledge-source.create`\n\n**Resource:** `chatbots/:chatbotId`"}}},"components":{"schemas":{"UploadFilesDto":{"type":"object","properties":{"files":{"type":"array","description":"Files to be uploaded as knowledge sources.","items":{"type":"string","format":"binary"}}},"required":["files"]},"UploadKnowledgeSourceFilesResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates whether the upload was successful."}}}}}}
```