Skip to Content

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 PUBLISHED entries are in the knowledge index. A DRAFT entry keeps its text, but the AI doesn’t see it. New entries start as PUBLISHED. Unpublish an entry to turn it into a draft, and publish it to bring it back.
  • Origin. origin records where an entry came from: INBOX for an answer saved from a conversation, for example an agent’s reply saved from the inbox, and MANUAL for an entry written from scratch. For INBOX entries, pass messageId and conversationId to 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 question and answer, 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 get You 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 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.

Q&A entry properties

PropertyTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The Q&A entry ID.

questionstring

The question, as a client would ask it.

answerstring

The answer the AI assistant should give.

statusQaStatus

PUBLISHED: in the knowledge index and used by the AI. DRAFT: saved, but not used by the AI.

originQaOrigin

INBOX: saved from a conversation. MANUAL: written from scratch.

messageIdstring

The ID of the message the entry was saved from, if any.

conversationIdstring

The ID of the conversation the entry was saved from, if any.

createdAtDateTime

The created timestamp.

patchedAtDateTime

When the entry was last updated, published or unpublished. null until then.

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

statusQaStatus

Return only entries with this status: DRAFT or PUBLISHED. Omit it to get both.

searchstring

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/gq
query 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.

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":"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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

questionstring

Required. The question to match. Must not be empty.

Request & Response

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

  1. 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 DRAFT and PUBLISHED entries.
  2. 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 PUBLISHED entries.

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 } } }
ErrorCause
Question is requiredquestion is empty or only whitespace.
Error searching similar Q&AThe knowledge index search failed. Try again.
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":"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).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

questionstring

Required. The question, as a client would ask it. Trimmed; must not be empty.

answerstring

Required. The answer the AI assistant should give. Trimmed; must not be empty.

originQaOrigin

Required. INBOX when the answer was saved from a conversation, MANUAL when it was written from scratch.

messageIdstring

The ID of the message the answer was saved from. Use it with origin: INBOX. Stored as given (trimmed); an empty value is stored as null.

conversationIdstring

The ID of the conversation the answer was saved from. Stored as given (trimmed); an empty value is stored as null.

Request & Response

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

ErrorCause
Question is requiredquestion is empty or only whitespace.
Answer is requiredanswer is empty or only whitespace.
Error embedding Q&AThe 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 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":"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).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The Q&A entry ID.

questionstring

Required. The new question. Trimmed; must not be empty.

answerstring

Required. The new answer. Trimmed; must not be empty.

Request & Response

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

ErrorCause
Q&A not foundNo Q&A entry with this id in the workspace.
Question is requiredquestion is empty or only whitespace.
Answer is requiredanswer is empty or only whitespace.
Error embedding Q&AThe 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 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":"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).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The Q&A entry ID.

Request & Response

POST https://gateway.bcrumbs.net/bot/gq
mutation 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" } } }
ErrorCause
Q&A not foundNo Q&A entry with this id in the workspace.
Error embedding Q&AThe 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 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":"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).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The Q&A entry ID.

Request & Response

POST https://gateway.bcrumbs.net/bot/gq
mutation 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" } } }
ErrorCause
Q&A not foundNo Q&A entry 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":"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).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The Q&A entry ID.

Request & Response

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

ErrorCause
Q&A not foundNo Q&A entry 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":"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}"}'