Skip to Content
API ReferenceKnowledge Sources

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

TypeFile extensionsHow 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 TXT. PDFs without a text layer, such as scanned pages, are rejected.

HTML`.html`, `.htm`

By h1 and h2 headings.

JSON`.json`

By JSON structure.

  • The file name decides how a file is read. The extension in name picks the reader. type is 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. name includes 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 get You 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 gets Missing 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.workspaceId names another workspace is rejected before any field runs, and a field whose own workspaceId names another workspace (written inline in the query, passed in another variable or sent in a later operation of a batch) fails with This API key can only access its own workspace.

Source properties

PropertyTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The source ID.

namestring

The file name, including the extension.

sizenumber

The file size in bytes, as given when the source was created. Counts toward the 200 MB workspace limit.

typeSourceType

The file type: MD, TXT, PDF, HTML or JSON.

createdAtDateTime

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

namestring

Return only sources whose name contains this text (case-insensitive).

typeSourceType

Return only sources of this type: MD, TXT, PDF, HTML or JSON.

Request & Response

POST https://gateway.bcrumbs.net/bot/gq
query 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" } ] } } }
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

namestring

Required. The file name, including the extension, for example shipping-faq.md. It must match the name of the file stored for the workspace. The extension decides how the file is read.

sizenumber

Required. The file size in bytes. Counts toward the 200 MB workspace limit. It isn't checked against the stored file.

typeSourceType

Required. MD, TXT, PDF, HTML or JSON. Use the type that matches the extension in name.

Request & Response

POST https://gateway.bcrumbs.net/bot/gq
mutation 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.

ErrorCause
Source with similar name already existsAn 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: 25MBThe 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 fileNo 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 RAGThe content couldn’t be split into passages or indexed.
Error processing file: Failed to store vectors in databaseThe passages couldn’t be saved to the knowledge index. Try again.
You do not have permission to access this resource with your current role assignmentThe calling user is a Manager, Agent+ or Agent, or the call uses an agent API key.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The source ID.

Request & Response

POST https://gateway.bcrumbs.net/bot/gq
mutation 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.

ErrorCause
Source not foundNo source with this id in the workspace.
Error processing file: Failed to download and process fileThe stored file is missing, or it’s a PDF without extractable text.
Error processing file: Failed to process content through RAGThe content couldn’t be split into passages or indexed.
Error processing file: Failed to store vectors in databaseThe passages couldn’t be saved to the knowledge index. Try again.
You do not have permission to access this resource with your current role assignmentThe calling user is a Manager, Agent+ or Agent, or the call uses an agent API key.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The source ID.

Request & Response

POST https://gateway.bcrumbs.net/bot/gq
mutation 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.

ErrorCause
Source not foundNo source with this id in the workspace.
You do not have permission to access this resource with your current role assignmentThe calling user is a Manager, Agent+ or Agent, or the call uses an agent API key.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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