Q&A APIs
Overview
A Q&A entry is a question paired with the answer your team wants the AI assistant to give. Published entries are part of the workspace knowledge that the Bread Crumbs AI assistant (Crumby) searches when a client writes. Crumby answers only from what it finds there, so a published entry is the most direct way to teach it a fact or a preferred answer.
- How the AI uses entries. Each published entry is stored in the workspace knowledge index as one item: the question and the answer together. The same index holds the passages of your knowledge sources. For each client message, Crumby looks up the closest items in the index and writes its reply from them.
- DRAFT and PUBLISHED. Only
PUBLISHEDentries are in the knowledge index. ADRAFTentry keeps its text, but the AI doesn’t see it. New entries start asPUBLISHED. Unpublish an entry to turn it into a draft, and publish it to bring it back. - Origin.
originrecords where an entry came from:INBOXfor an answer saved from a conversation, for example an agent’s reply saved from the inbox, andMANUALfor an entry written from scratch. ForINBOXentries, passmessageIdandconversationIdto link the entry to the message it came from. Origin doesn’t change how the AI uses the entry. - No duplicate check. Creating an entry never checks for an existing entry with the same question. Call Find Similar Q&A first.
- Values are trimmed. Leading and trailing whitespace is removed from
questionandanswer, and empty values are rejected. - Who can do what. Any role on the workspace can list entries and find similar ones. Creating, updating, publishing, unpublishing and deleting entries 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 Q&A API. Agent API keys of any role can read entries 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.
Q&A entry properties
| Property | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The Q&A entry ID. |
question | string | The question, as a client would ask it. |
answer | string | The answer the AI assistant should give. |
status | QaStatus |
|
origin | QaOrigin |
|
messageId | string | The ID of the message the entry was saved from, if any. |
conversationId | string | The ID of the conversation the entry was saved from, if any. |
createdAt | DateTime | The created timestamp. |
patchedAt | DateTime | When the entry was last updated, published or unpublished. |
List Q&A Entries API
Get the Q&A entries of a workspace, newest first. The list is not paginated. Filter by status, by a search term, or both.
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. |
status | QaStatus | Return only entries with this status: |
search | string | Text to look for. It's trimmed and matched as a case-insensitive substring of the question or the answer. An empty value is ignored. |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqquery qaEntries($input: QaEntriesInput!) {
qaEntries(input: $input) {
nodes {
id
question
answer
status
origin
createdAt
patchedAt
}
}
}
input QaEntriesInput {
workspaceId: Int! # Workspace ID.
status: QaStatus # DRAFT or PUBLISHED; omit for both.
search: String # Case-insensitive text in the question or answer.
}
enum QaStatus {
DRAFT # Saved, not used by the AI.
PUBLISHED # In the knowledge index, used by the AI.
}The query above returns JSON structured like this:
{
"data": {
"qaEntries": {
"nodes": [
{
"id": "qa_124",
"question": "How long does a refund take?",
"answer": "Refunds reach your card within 5 to 7 business days after we approve them.",
"status": "PUBLISHED",
"origin": "MANUAL",
"createdAt": "2026-10-17T09:30:00.000Z",
"patchedAt": null
},
{
"id": "qa_123",
"question": "Can I get a refund?",
"answer": "Yes. You can request a full refund within 30 days of purchase from Orders > Request refund.",
"status": "PUBLISHED",
"origin": "INBOX",
"createdAt": "2026-10-02T14:05:00.000Z",
"patchedAt": "2026-10-10T08:15:00.000Z"
}
]
}
}
}search is a plain text match, not a search by meaning: refund finds “Can I get a refund?” but not “Can I get my money back?”. To find an entry by meaning, use Find Similar Q&A.
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/bot/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"qaEntries","variables":{"input":{"workspaceId":12,"status":"PUBLISHED","search":"refund"}},"query":"query qaEntries($input: QaEntriesInput!) {\n qaEntries(input: $input) {\n nodes {\n id\n question\n answer\n status\n origin\n createdAt\n patchedAt\n }\n }\n}"}'Find Similar Q&A API
Find the existing Q&A entry that best matches a question. Use it before creating an entry to avoid duplicates, or to look up the saved answer to a client’s question. Returns entry: null when nothing matches.
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. |
question | string | Required. The question to match. Must not be empty. |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqquery similarQa($input: SimilarQaInput!) {
similarQa(input: $input) {
entry {
id
question
answer
status
origin
}
}
}
input SimilarQaInput {
workspaceId: Int! # Workspace ID.
question: String! # The question to match.
}The query above returns JSON structured like this:
{
"data": {
"similarQa": {
"entry": {
"id": "qa_123",
"question": "Can I get a refund?",
"answer": "Yes. You can request a full refund within 30 days of purchase from Orders > Request refund.",
"status": "PUBLISHED",
"origin": "INBOX"
}
}
}
}The match is found in two steps:
- Same wording. The question is compared with the question of every entry, ignoring case, leading and trailing whitespace, and repeated spaces. If one matches, it’s returned right away (the newest one if several match). This step checks
DRAFTandPUBLISHEDentries. - Same meaning. Otherwise, the AI model turns the question into a numeric representation of its meaning and compares it with the published entries in the knowledge index, each stored as its question and answer together. The similarity is a score from 0 to 1. Only entries scoring at least 0.82 count, and the highest-scoring one is returned. Drafts aren’t in the index, so this step only finds
PUBLISHEDentries.
The second step looks at the 10 items in the workspace knowledge index closest to the question. Passages from knowledge sources share that index, so when many of them are closer to the question than any entry, a matching entry can be missed.
When nothing matches, the response is:
{
"data": {
"similarQa": {
"entry": null
}
}
}| Error | Cause |
|---|---|
Question is required | question is empty or only whitespace. |
Error searching similar Q&A | The knowledge index search failed. Try again. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/bot/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"similarQa","variables":{"input":{"workspaceId":12,"question":"Can I get my money back?"}},"query":"query similarQa($input: SimilarQaInput!) {\n similarQa(input: $input) {\n entry {\n id\n question\n answer\n status\n origin\n }\n }\n}"}'Create Q&A Entry API
Create a Q&A entry. The entry is created as PUBLISHED and added to the knowledge index right away, so the AI assistant can use it in its next replies. There is no duplicate check; call Find Similar Q&A first if you don’t want two entries for the same question.
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. |
question | string | Required. The question, as a client would ask it. Trimmed; must not be empty. |
answer | string | Required. The answer the AI assistant should give. Trimmed; must not be empty. |
origin | QaOrigin | Required. |
messageId | string | The ID of the message the answer was saved from. Use it with |
conversationId | string | The ID of the conversation the answer was saved from. Stored as given (trimmed); an empty value is stored as |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqmutation createQa($input: QaCreateInput!) {
createQa(input: $input) {
id
question
answer
status
origin
messageId
conversationId
createdAt
}
}
input QaCreateInput {
workspaceId: Int! # Workspace ID.
question: String! # The question.
answer: String! # The answer.
origin: QaOrigin! # INBOX or MANUAL.
messageId: String # Message the answer came from.
conversationId: String # Conversation the answer came from.
}
enum QaOrigin {
INBOX # Saved from a conversation.
MANUAL # Written from scratch.
}The mutation above returns JSON structured like this:
{
"data": {
"createQa": {
"id": "qa_123",
"question": "Can I get a refund?",
"answer": "Yes. You can request a full refund within 30 days of purchase from Orders > Request refund.",
"status": "PUBLISHED",
"origin": "INBOX",
"messageId": "msg_123",
"conversationId": "conv_123",
"createdAt": "2026-10-17T09:30:00.000Z"
}
}
}messageId and conversationId aren’t checked; they’re stored for reference only. If the entry can’t be added to the knowledge index, it’s removed again, so a failed call saves nothing.
| Error | Cause |
|---|---|
Question is required | question is empty or only whitespace. |
Answer is required | answer is empty or only whitespace. |
Error embedding Q&A | The entry couldn’t be added to the knowledge index. Nothing is saved; 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":"createQa","variables":{"input":{"workspaceId":12,"question":"Can I get a refund?","answer":"Yes. You can request a full refund within 30 days of purchase from Orders > Request refund.","origin":"INBOX","messageId":"msg_123","conversationId":"conv_123"}},"query":"mutation createQa($input: QaCreateInput!) {\n createQa(input: $input) {\n id\n question\n answer\n status\n origin\n messageId\n conversationId\n createdAt\n }\n}"}'Update Q&A Entry API
Replace the question and answer of a Q&A entry. Send both fields, even if only one changes. If the entry is PUBLISHED, its knowledge index item is rebuilt with the new text, so the AI assistant uses the new answer right away; a DRAFT stays a draft. Sets patchedAt.
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 Q&A entry ID. |
question | string | Required. The new question. Trimmed; must not be empty. |
answer | string | Required. The new answer. Trimmed; must not be empty. |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqmutation updateQa($input: QaUpdateInput!) {
updateQa(input: $input) {
id
question
answer
status
patchedAt
}
}
input QaUpdateInput {
workspaceId: Int! # Workspace ID.
id: ID! # Q&A entry ID.
question: String! # New question.
answer: String! # New answer.
}The mutation above returns JSON structured like this:
{
"data": {
"updateQa": {
"id": "qa_123",
"question": "Can I get a refund?",
"answer": "Yes. You can request a full refund within 60 days of purchase from Orders > Request refund.",
"status": "PUBLISHED",
"patchedAt": "2026-10-17T09:30:00.000Z"
}
}
}If a published entry fails with Error embedding Q&A, try again: the entry keeps its old text, but its old item has already been removed from the knowledge index, so the AI doesn’t use it until an update succeeds.
| Error | Cause |
|---|---|
Q&A not found | No Q&A entry with this id in the workspace. |
Question is required | question is empty or only whitespace. |
Answer is required | answer is empty or only whitespace. |
Error embedding Q&A | The published entry couldn’t be added to the knowledge index with the new text. |
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":"updateQa","variables":{"input":{"workspaceId":12,"id":"qa_123","question":"Can I get a refund?","answer":"Yes. You can request a full refund within 60 days of purchase from Orders > Request refund."}},"query":"mutation updateQa($input: QaUpdateInput!) {\n updateQa(input: $input) {\n id\n question\n answer\n status\n patchedAt\n }\n}"}'Publish Q&A Entry API
Publish a draft Q&A entry. The entry is added to the knowledge index, so the AI assistant starts using it, and its status becomes PUBLISHED. Sets patchedAt. Publishing an entry that is already PUBLISHED returns it unchanged.
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 Q&A entry ID. |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqmutation publishQa($input: QaIdInput!) {
publishQa(input: $input) {
id
status
patchedAt
}
}
input QaIdInput {
workspaceId: Int! # Workspace ID.
id: ID! # Q&A entry ID.
}The mutation above returns JSON structured like this:
{
"data": {
"publishQa": {
"id": "qa_123",
"status": "PUBLISHED",
"patchedAt": "2026-10-17T09:30:00.000Z"
}
}
}| Error | Cause |
|---|---|
Q&A not found | No Q&A entry with this id in the workspace. |
Error embedding Q&A | The entry couldn’t be added to the knowledge index. It stays DRAFT; 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":"publishQa","variables":{"input":{"workspaceId":12,"id":"qa_123"}},"query":"mutation publishQa($input: QaIdInput!) {\n publishQa(input: $input) {\n id\n status\n patchedAt\n }\n}"}'Unpublish Q&A Entry API
Turn a Q&A entry into a draft. The entry is removed from the knowledge index, so the AI assistant stops using it, and its status becomes DRAFT. The question and answer are kept. Sets patchedAt. Unpublishing a draft returns it unchanged.
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 Q&A entry ID. |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqmutation unpublishQa($input: QaIdInput!) {
unpublishQa(input: $input) {
id
status
patchedAt
}
}
input QaIdInput {
workspaceId: Int! # Workspace ID.
id: ID! # Q&A entry ID.
}The mutation above returns JSON structured like this:
{
"data": {
"unpublishQa": {
"id": "qa_123",
"status": "DRAFT",
"patchedAt": "2026-10-17T09:30:00.000Z"
}
}
}| Error | Cause |
|---|---|
Q&A not found | No Q&A entry 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":"unpublishQa","variables":{"input":{"workspaceId":12,"id":"qa_123"}},"query":"mutation unpublishQa($input: QaIdInput!) {\n unpublishQa(input: $input) {\n id\n status\n patchedAt\n }\n}"}'Delete Q&A Entry API
Permanently delete a Q&A entry. Its item is removed from the knowledge index, so the AI assistant stops using it, and then the entry itself is deleted. The response returns the entry 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 Q&A entry ID. |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqmutation deleteQa($input: QaIdInput!) {
deleteQa(input: $input) {
id
question
status
}
}
input QaIdInput {
workspaceId: Int! # Workspace ID.
id: ID! # Q&A entry ID.
}The mutation above returns JSON structured like this:
{
"data": {
"deleteQa": {
"id": "qa_123",
"question": "Can I get a refund?",
"status": "PUBLISHED"
}
}
}This is a hard delete: the entry can’t be restored and no longer appears in List Q&A Entries. To take an answer away from the AI but keep it, unpublish it instead.
| Error | Cause |
|---|---|
Q&A not found | No Q&A entry 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":"deleteQa","variables":{"input":{"workspaceId":12,"id":"qa_123"}},"query":"mutation deleteQa($input: QaIdInput!) {\n deleteQa(input: $input) {\n id\n question\n status\n }\n}"}'