Knowledge Sources APIs
Overview
A knowledge source is a file whose content the AI assistant uses to answer clients. When a source is created, its file is read, split into short passages and added to the workspace knowledge index. The Bread Crumbs AI assistant (Crumby) searches that index for each client message and answers only from what it finds. The same index also holds your published Q&A entries.
You can manage sources in the portal: upload documents on Crumby files and write Markdown snippets on Crumby text. Snippets are saved as MD sources.
createSource doesn’t carry the file content. It registers and indexes a file that is already stored for the workspace under the same name. The portal stores the file for you when you upload a document or save a snippet, then calls createSource. The file upload step itself isn’t part of the documented API.
Supported source types
| Type | File extensions | How the content is split |
|---|---|---|
MD | `.md`, `.markdown` | By Markdown section. Short sections are merged. |
TXT | `.txt` | Into passages of whole sentences. |
PDF | `.pdf` | The text is extracted and split like |
HTML | `.html`, `.htm` | By |
JSON | `.json` | By JSON structure. |
- The file name decides how a file is read. The extension in
namepicks the reader.typeis stored for display and filtering only, so keep the two consistent. Files with other extensions are rejected. - Size limit. All sources of a workspace can add up to 200 MB (209,715,200 bytes), counted from each source’s
size. The portal also limits each upload to 20 MB. - Names are file names.
nameincludes the extension and identifies the stored file, so each source needs its own name (see Create Source). - Who can do what. Any role on the workspace can list sources. Creating, re-indexing and deleting sources needs the Owner or Admin role (
MANAGE_WORKSPACE); other roles getYou do not have permission to access this resource with your current role assignment. Workspace API keys can call every source API. Agent API keys of any role can list sources but can’t change them. A user with no role in the workspace getsMissing role assignment for the target user. - API keys stay in their workspace. An API key only works in its own workspace. A request whose
input.workspaceIdnames another workspace is rejected before any field runs, and a field whose ownworkspaceIdnames another workspace (written inline in the query, passed in another variable or sent in a later operation of a batch) fails withThis API key can only access its own workspace.
Source properties
| Property | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The source ID. |
name | string | The file name, including the extension. |
size | number | The file size in bytes, as given when the source was created. Counts toward the 200 MB workspace limit. |
type | SourceType | The file type: |
createdAt | DateTime | The created timestamp. |
List Sources API
Get the knowledge sources of a workspace, newest first. The list is not paginated.
Access: Any role on the workspace (Owner, Admin, Manager, Agent+ or Agent). Works with workspace API keys and with agent API keys of any role, in the key’s own workspace.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
name | string | Return only sources whose name contains this text (case-insensitive). |
type | SourceType | Return only sources of this type: |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqquery sources($input: SourcesInput!) {
sources(input: $input) {
nodes {
id
name
size
type
createdAt
}
}
}
input SourcesInput {
workspaceId: Int! # Workspace ID.
name: String # Case-insensitive text in the name.
type: SourceType # Only this type.
}
enum SourceType {
MD # Markdown (.md, .markdown)
TXT # Plain text (.txt)
PDF # PDF with a text layer (.pdf)
HTML # HTML (.html, .htm)
JSON # JSON (.json)
}The query above returns JSON structured like this:
{
"data": {
"sources": {
"nodes": [
{
"id": "source_124",
"name": "pricing-2026.pdf",
"size": 482133,
"type": "PDF",
"createdAt": "2026-10-17T09:30:00.000Z"
},
{
"id": "source_123",
"name": "return-policy.pdf",
"size": 210544,
"type": "PDF",
"createdAt": "2026-10-02T14:05:00.000Z"
}
]
}
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/bot/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"sources","variables":{"input":{"workspaceId":12,"type":"PDF"}},"query":"query sources($input: SourcesInput!) {\n sources(input: $input) {\n nodes {\n id\n name\n size\n type\n createdAt\n }\n }\n}"}'Create Source API
Register a stored file as a knowledge source and add its content to the knowledge index. The call reads the workspace file named name, splits it into passages, indexes them and then creates the source. It returns once indexing is done, so the AI assistant can use the content right away. The file must already be stored (see the note in Overview).
Access: Owner or Admin (MANAGE_WORKSPACE). Works with workspace API keys. Agent API keys can’t call it, whatever their role (Manager, Agent+ or Agent).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
name | string | Required. The file name, including the extension, for example |
size | number | Required. The file size in bytes. Counts toward the 200 MB workspace limit. It isn't checked against the stored file. |
type | SourceType | Required. |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqmutation createSource($input: SourceCreateInput!) {
createSource(input: $input) {
id
name
size
type
createdAt
}
}
input SourceCreateInput {
workspaceId: Int! # Workspace ID.
name: String! # File name with extension.
size: Int! # File size in bytes.
type: SourceType! # File type.
}
enum SourceType {
MD # Markdown (.md, .markdown)
TXT # Plain text (.txt)
PDF # PDF with a text layer (.pdf)
HTML # HTML (.html, .htm)
JSON # JSON (.json)
}The mutation above returns JSON structured like this:
{
"data": {
"createSource": {
"id": "source_125",
"name": "shipping-faq.md",
"size": 18342,
"type": "MD",
"createdAt": "2026-10-17T09:30:00.000Z"
}
}
}The checks run in this order: name, size limit, then indexing. If one fails, no source is created.
| Error | Cause |
|---|---|
Source with similar name already exists | An existing source’s name contains name (case-insensitive). For example, faq.md is rejected while shipping-faq.md exists. |
Adding this source would exceed the 200MB workspace limit. Current usage: 180MB, attempting to add: 25MB | The sizes of the existing sources plus size exceed 200 MB. The numbers are your current usage and size, rounded to whole MB. |
Error processing file: Failed to download and process file | No file named name is stored for the workspace, its extension isn’t supported, or it’s a PDF without extractable text. |
Error processing file: Failed to process content through RAG | The content couldn’t be split into passages or indexed. |
Error processing file: Failed to store vectors in database | The passages couldn’t be saved to the knowledge index. Try again. |
You do not have permission to access this resource with your current role assignment | The calling user is a Manager, Agent+ or Agent, or the call uses an agent API key. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/bot/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"createSource","variables":{"input":{"workspaceId":12,"name":"shipping-faq.md","size":18342,"type":"MD"}},"query":"mutation createSource($input: SourceCreateInput!) {\n createSource(input: $input) {\n id\n name\n size\n type\n createdAt\n }\n}"}'Re-index Source API
Rebuild the knowledge index for a source from its stored file (patchSource). The source’s passages are removed from the knowledge index, and the stored file is read and indexed again. Use it after the stored file’s content changed; the portal does this when you edit a Crumby text snippet.
Access: Owner or Admin (MANAGE_WORKSPACE). Works with workspace API keys. Agent API keys can’t call it, whatever their role (Manager, Agent+ or Agent).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The source ID. |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqmutation patchSource($input: SourcePatchInput!) {
patchSource(input: $input) {
id
name
size
type
}
}
input SourcePatchInput {
workspaceId: Int! # Workspace ID.
id: ID! # Source ID.
}The mutation above returns JSON structured like this:
{
"data": {
"patchSource": {
"id": "source_125",
"name": "shipping-faq.md",
"size": 18342,
"type": "MD"
}
}
}The source itself isn’t changed: name, type and size keep the values given at creation, even if the stored file is now larger or smaller. If indexing fails, the old passages are already gone, so the AI doesn’t use this source until a re-index succeeds.
| Error | Cause |
|---|---|
Source not found | No source with this id in the workspace. |
Error processing file: Failed to download and process file | The stored file is missing, or it’s a PDF without extractable text. |
Error processing file: Failed to process content through RAG | The content couldn’t be split into passages or indexed. |
Error processing file: Failed to store vectors in database | The passages couldn’t be saved to the knowledge index. Try again. |
You do not have permission to access this resource with your current role assignment | The calling user is a Manager, Agent+ or Agent, or the call uses an agent API key. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/bot/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"patchSource","variables":{"input":{"workspaceId":12,"id":"source_125"}},"query":"mutation patchSource($input: SourcePatchInput!) {\n patchSource(input: $input) {\n id\n name\n size\n type\n }\n}"}'Delete Source API
Permanently delete a knowledge source. The call removes the stored file, removes the source’s passages from the knowledge index so the AI assistant stops using them, and then deletes the source. The response returns the source as it was before deletion.
Access: Owner or Admin (MANAGE_WORKSPACE). Works with workspace API keys. Agent API keys can’t call it, whatever their role (Manager, Agent+ or Agent).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The source ID. |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqmutation deleteSource($input: SourceDeleteInput!) {
deleteSource(input: $input) {
id
name
size
type
createdAt
}
}
input SourceDeleteInput {
workspaceId: Int! # Workspace ID.
id: ID! # Source ID.
}The mutation above returns JSON structured like this:
{
"data": {
"deleteSource": {
"id": "source_125",
"name": "shipping-faq.md",
"size": 18342,
"type": "MD",
"createdAt": "2026-10-17T09:30:00.000Z"
}
}
}This is a hard delete: the source can’t be restored, and its size no longer counts toward the 200 MB limit. If the stored file is already gone or can’t be removed, the call still removes the passages and the source.
| Error | Cause |
|---|---|
Source not found | No source with this id in the workspace. |
You do not have permission to access this resource with your current role assignment | The calling user is a Manager, Agent+ or Agent, or the call uses an agent API key. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/bot/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"deleteSource","variables":{"input":{"workspaceId":12,"id":"source_125"}},"query":"mutation deleteSource($input: SourceDeleteInput!) {\n deleteSource(input: $input) {\n id\n name\n size\n type\n createdAt\n }\n}"}'