Voiceflow bearer token
Knowledge bases
Give your agent answers from your own content.
Paste in your agent
1. Set up Voiceflow by following https://www.voiceflow.com/agents/setup 2. Read https://www.voiceflow.com/docs/api-reference/resources/knowledge-base.md — the Voiceflow documentation page "Knowledge bases". Use it to help me with this part of Voiceflow and answer my questions. Refer to https://www.voiceflow.com/docs/llms.txt if you need related documentation.
See Authentication for credentials and permissions.
Current - 2026/07
/v1/stable/knowledge-base/querySearches the knowledge base and returns the passages a retrieval would surface, which is how to see what an agent will be grounded on before it answers.
curl --request POST \
--url 'https://realtime-api.voiceflow.com/v1/stable/knowledge-base/query?projectID=<projectID>&environmentAlias=<environmentAlias>' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"version": "draft",
"filters": {},
"question": "<string>",
"settings": {
"model": "gpt-3.5-turbo-1106",
"system": "<string>",
"maxTokens": 0,
"temperature": 0,
"reasoningEffort": "off"
},
"synthesis": true,
"chunkLimit": 0,
"instruction": "<string>"
}'const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/knowledge-base/query?projectID=<projectID>&environmentAlias=<environmentAlias>', {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"version": "draft",
"filters": {},
"question": "<string>",
"settings": {
"model": "gpt-3.5-turbo-1106",
"system": "<string>",
"maxTokens": 0,
"temperature": 0,
"reasoningEffort": "off"
},
"synthesis": true,
"chunkLimit": 0,
"instruction": "<string>"
}),
});
const data = await response.json();import requests
response = requests.post(
'https://realtime-api.voiceflow.com/v1/stable/knowledge-base/query?projectID=<projectID>&environmentAlias=<environmentAlias>',
headers={'Authorization': 'Bearer <token>'},
json={
"version": "draft",
"filters": {},
"question": "<string>",
"settings": {
"model": "gpt-3.5-turbo-1106",
"system": "<string>",
"maxTokens": 0,
"temperature": 0,
"reasoningEffort": "off"
},
"synthesis": True,
"chunkLimit": 0,
"instruction": "<string>"
},
)
data = response.json()vf knowledge-base query --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
"version": "draft",
"filters": {},
"question": "<string>",
"settings": {
"model": "gpt-3.5-turbo-1106",
"system": "<string>",
"maxTokens": 0,
"temperature": 0,
"reasoningEffort": "off"
},
"synthesis": true,
"chunkLimit": 0,
"instruction": "<string>"
}
JSON{
"answer": {
"model": "gpt-3.5-turbo-1106",
"output": "<string>",
"tokens": 0,
"duration": 0,
"queryTokens": 0,
"answerTokens": 0,
"inputMultiplier": 0,
"cacheMultiplier": 0,
"outputMultiplier": 0,
"cacheWriteTokens": 0,
"queryCachedTokens": 0,
"cacheWriteMultiplier": 0,
"queryRemainderTokens": 0,
"base": {
"queryTokens": 0,
"answerTokens": 0,
"cacheWriteTokens": 0,
"queryCachedTokens": 0
},
"priorityMultipliers": {
"inputMultiplier": 0,
"cacheMultiplier": 0,
"outputMultiplier": 0,
"cacheWriteMultiplier": 0
},
"chunks": [
{
"score": 0,
"chunkID": "<string>",
"documentID": "<string>",
"content": "<string>",
"source": "<KBDocumentData>",
"metadata": {}
}
]
}
}Authentication
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Whether to query the draft or the published version of the knowledge base.
draft, publishedMetadata filters used to narrow down which document chunks are searched.
The natural-language question to ask the knowledge base.
Show child attributes
The AI model used to synthesize the answer.
gpt-3.5-turbo-1106, gpt-3.5-turbo, gpt-4, gpt-4o, gpt-4o-mini, gpt-4.1-2025-04-14, gpt-4.1-mini-2025-04-14, gpt-4.1-nano-2025-04-14, gpt-o3-mini, o3-2025-04-16, o4-mini-2025-04-16, gpt-5, gpt-5-mini, gpt-5-nano, gpt-5.2, gpt-5.4, gpt-5.4-mini, gpt-5.5, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-6-sol, gpt-6-luna, gpt-6.1-sol, gpt-realtime, gpt-live-1, claude-4-opus, claude-4-sonnet, claude-4.5-sonnet, claude-4.6-sonnet, claude-4.5-haiku, claude-4.5-opus, claude-4.7-opus, bedrock-claude-4-sonnet, bedrock-claude-4.5-sonnet, bedrock-claude-4.6-sonnet, bedrock-claude-5-sonnet, bedrock-claude-5.5-sonnet, bedrock-claude-4.5-haiku, bedrock-claude-5.5-haiku, bedrock-claude-4.5-opus, bedrock-claude-4.7-opus, bedrock-claude-4.8-opus, voiceflow-core-4.0, voiceflow-core-4.1, voiceflow-core-4.2, voiceflow-flash-4.2, gemini-2.5-pro, gemini-2.5-flash, gemini-live-2.5-flash, gemini-3-flash, gemini-3.5-flash, gemini-3.1-pro, gpt-oss-20b, gpt-oss-120b, llama-guard-4, llama-3.1-instant, llama-3.3-versatile, qwen3.6-27b, grok-4.6, voiceflow-flash-4.1, kimi-k3, gemini-flash-2, gpt-4-turbo, claude-3.5-haiku, claude-3-opus, claude-3.7-sonnet, claude-v2, llama-3.2-1b-preview, gemini-pro-1.5, claude-3-haiku, claude-3-sonnet, text-davinci-003, claude-v1, claude-instant-v1, deep-seek-r1-distill-llama-70B, claude-3.5-sonnetThe system prompt applied to the model when synthesizing the answer.
Deprecated. The model's default output limit applies when this is lower or unset, and the model's maximum caps it.
The sampling temperature applied to the model when synthesizing the answer.
The reasoning effort applied to the model when synthesizing the answer.
off, adaptive, minimal, low, medium, highWhether to synthesize an answer from the retrieved chunks; when false, only raw chunks are returned.
The maximum number of document chunks to retrieve.
An additional instruction applied when synthesizing the answer from the retrieved chunks.
Response
200 - application/jsonReturns the answer generated from the knowledge base and the chunks it was drawn from, alongside the model used, the duration, and the token accounting for the call.
The result of the knowledge base query, including the synthesized answer and token usage.
Show child attributes
The AI model used to answer the query.
gpt-3.5-turbo-1106, gpt-3.5-turbo, gpt-4, gpt-4o, gpt-4o-mini, gpt-4.1-2025-04-14, gpt-4.1-mini-2025-04-14, gpt-4.1-nano-2025-04-14, gpt-o3-mini, o3-2025-04-16, o4-mini-2025-04-16, gpt-5, gpt-5-mini, gpt-5-nano, gpt-5.2, gpt-5.4, gpt-5.4-mini, gpt-5.5, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-6-sol, gpt-6-luna, gpt-6.1-sol, gpt-realtime, gpt-live-1, claude-4-opus, claude-4-sonnet, claude-4.5-sonnet, claude-4.6-sonnet, claude-4.5-haiku, claude-4.5-opus, claude-4.7-opus, bedrock-claude-4-sonnet, bedrock-claude-4.5-sonnet, bedrock-claude-4.6-sonnet, bedrock-claude-5-sonnet, bedrock-claude-5.5-sonnet, bedrock-claude-4.5-haiku, bedrock-claude-5.5-haiku, bedrock-claude-4.5-opus, bedrock-claude-4.7-opus, bedrock-claude-4.8-opus, voiceflow-core-4.0, voiceflow-core-4.1, voiceflow-core-4.2, voiceflow-flash-4.2, gemini-2.5-pro, gemini-2.5-flash, gemini-live-2.5-flash, gemini-3-flash, gemini-3.5-flash, gemini-3.1-pro, gpt-oss-20b, gpt-oss-120b, llama-guard-4, llama-3.1-instant, llama-3.3-versatile, qwen3.6-27b, grok-4.6, voiceflow-flash-4.1, kimi-k3, gemini-flash-2, gpt-4-turbo, claude-3.5-haiku, claude-3-opus, claude-3.7-sonnet, claude-v2, llama-3.2-1b-preview, gemini-pro-1.5, claude-3-haiku, claude-3-sonnet, text-davinci-003, claude-v1, claude-instant-v1, deep-seek-r1-distill-llama-70B, claude-3.5-sonnetThe synthesized answer text, or null when no answer was generated.
The total number of tokens consumed by the query.
The time it took to execute the query.
The number of input tokens consumed by the query, after multipliers.
The number of output tokens consumed by the answer, after multipliers.
The billing multiplier applied to input tokens.
The billing multiplier applied to cached input tokens.
The billing multiplier applied to output tokens.
The number of input tokens written to the prompt cache.
The number of input tokens read from the prompt cache.
The billing multiplier applied to cache-write tokens.
The number of input tokens that were not served from the prompt cache.
The raw token counts before billing multipliers are applied.
Show child attributes
The raw number of input tokens consumed by the query.
The raw number of output tokens consumed by the answer.
The raw number of input tokens written to the prompt cache.
The raw number of input tokens read from the prompt cache.
The billing multipliers applied when the query runs with priority processing.
Show child attributes
The priority billing multiplier applied to input tokens.
The priority billing multiplier applied to cached input tokens.
The priority billing multiplier applied to output tokens.
The priority billing multiplier applied to cache-write tokens.
Show child attributes
Legacy - 2023/05
/knowledge-base/queryQuery the knowledge base and retrieve answers to user questions. Send a question and receive a synthesized answer or relevant document chunks from the knowledge base.
curl --request POST \
--url 'https://general-runtime.voiceflow.com/knowledge-base/query' \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"projectID": "<string>",
"question": "<string>",
"instruction": "<string>",
"chunkLimit": 0,
"synthesis": true,
"settings": {
"model": "<string>",
"temperature": 0,
"maxTokens": 0,
"system": "<string>",
"reasoningEffort": "<string>"
},
"filters": {},
"internalFilters": [
{
"key": "<string>",
"value": "<string>",
"operator": "is"
}
],
"projectEnvironmentIDOrAlias": "<string>",
"versionVariant": "published"
}'const response = await fetch('https://general-runtime.voiceflow.com/knowledge-base/query', {
method: 'POST',
headers: {
Authorization: '<api-key>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"projectID": "<string>",
"question": "<string>",
"instruction": "<string>",
"chunkLimit": 0,
"synthesis": true,
"settings": {
"model": "<string>",
"temperature": 0,
"maxTokens": 0,
"system": "<string>",
"reasoningEffort": "<string>"
},
"filters": {},
"internalFilters": [
{
"key": "<string>",
"value": "<string>",
"operator": "is"
}
],
"projectEnvironmentIDOrAlias": "<string>",
"versionVariant": "published"
}),
});
const data = await response.json();import requests
response = requests.post(
'https://general-runtime.voiceflow.com/knowledge-base/query',
headers={'Authorization': '<api-key>'},
json={
"projectID": "<string>",
"question": "<string>",
"instruction": "<string>",
"chunkLimit": 0,
"synthesis": True,
"settings": {
"model": "<string>",
"temperature": 0,
"maxTokens": 0,
"system": "<string>",
"reasoningEffort": "<string>"
},
"filters": {},
"internalFilters": [
{
"key": "<string>",
"value": "<string>",
"operator": "is"
}
],
"projectEnvironmentIDOrAlias": "<string>",
"versionVariant": "published"
},
)
data = response.json(){
"type": "completion",
"model": "<string>",
"output": "<string>",
"duration": 0,
"tokens": 0,
"queryTokens": 0,
"answerTokens": 0,
"cacheWriteTokens": 0,
"queryCachedTokens": 0,
"queryRemainderTokens": 0,
"inputMultiplier": 0,
"cacheMultiplier": 0,
"outputMultiplier": 0,
"cacheWriteMultiplier": 0,
"base": {
"queryTokens": 0,
"answerTokens": 0,
"cacheWriteTokens": 0,
"queryCachedTokens": 0
},
"chunks": [
{
"score": 0,
"chunkID": "<string>",
"documentID": "<string>",
"content": "<string>",
"source": "<Legacy9_KBDocumentData>",
"metadata": {},
"internalMetadata": [
"<Legacy9_DocumentMetadataFields>"
]
}
]
}Authentication
Voiceflow API key
Request body
Show child attributes
The alias of the environment to target (ie. main). You can find this in the environments page of your agent.
> 💡 Tip: Learn more about Environments.
draft, publishedResponse
200 - application/jsoncompletionShow child attributes
Show child attributes
Show child attributes
Schemas
KBDocumentCSVData / Legacy9_KBDocumentCSVData
{"type":"object"}
| Property | Definition |
|---|---|
type · required | {"type":"string","enum":["csv"],"x-enumNames":["CSV"]} |
name · required | {"type":"string"} |
rowsCount | {"type":"number"} |
url | {"nullable":true,"type":"string"} |
KBDocumentData
{"oneOf":[{"$ref":"KBDocumentUrlData"},{"$ref":"KBDocumentDocxData"},{"$ref":"KBDocumentPDFData"},{"$ref":"KBDocumentTextData"},{"$ref":"KBDocumentMarkdownData"},{"$ref":"KBDocumentCSVData"},{"$ref":"KBDocumentXLSXData"},{"$ref":"KBDocumentTableData"},{"$ref":"KBDocumentSitemapData"},{"$ref":"KBDocumentIntegrationData"}]}
KBDocumentDocxData / Legacy9_KBDocumentDocxData
{"type":"object"}
| Property | Definition |
|---|---|
type · required | {"type":"string","enum":["docx"],"x-enumNames":["DOCX"]} |
name · required | {"type":"string"} |
url | {"nullable":true,"type":"string"} |
KBDocumentIntegrationConfig
{"type":"object"}
| Property | Definition |
|---|---|
filters · required | {"type":"object","additionalProperties":{}} |
preserveStructure · required | {"type":"boolean"} |
importMetadata · required | {"type":"boolean"} |
connection · required | {"type":"object","properties":{"fingerprint":{"type":"string"}},"required":["fingerprint"]} |
exclude · required | {"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"}},"required":["key","name"]}} |
KBDocumentIntegrationData
{"type":"object"}
| Property | Definition |
|---|---|
type · required | {"type":"string","enum":["integration"],"x-enumNames":["INTEGRATION"]} |
name · required | {"type":"string"} |
source · required | {"$ref":"KnowledgeBaseDocumentIntegrationType"} |
config · required | {"$ref":"KBDocumentIntegrationConfig"} |
refreshRate | {"allOf":[{"$ref":"KnowledgeBaseDocumentRefreshRate"}]} |
lastSuccessUpdate | {"type":"string"} |
sync | {"nullable":true,"allOf":[{"$ref":"KBDocumentSitemapSync"}]} |
KBDocumentMarkdownData / Legacy9_KBDocumentMarkdownData
{"type":"object"}
| Property | Definition |
|---|---|
type · required | {"type":"string","enum":["md"],"x-enumNames":["MD"]} |
name · required | {"type":"string"} |
url | {"nullable":true,"type":"string"} |
KBDocumentPDFData / Legacy9_KBDocumentPDFData
{"type":"object"}
| Property | Definition |
|---|---|
type · required | {"type":"string","enum":["pdf"],"x-enumNames":["PDF"]} |
name · required | {"type":"string"} |
url | {"nullable":true,"type":"string"} |
KBDocumentSitemapData
{"type":"object"}
| Property | Definition |
|---|---|
type · required | {"type":"string","enum":["sitemap"],"x-enumNames":["SITEMAP"]} |
name · required | {"type":"string"} |
url · required | {"type":"string"} |
refreshRate | {"allOf":[{"$ref":"KnowledgeBaseDocumentRefreshRate"}]} |
refreshTime | {"nullable":true,"type":"string","pattern":"^([01]\\d|2[0-3]):(00|30)$"} |
refreshTimezone | {"nullable":true,"type":"string"} |
lastSuccessUpdate | {"type":"string"} |
lastRefreshScheduledFor | {"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"} |
patterns | {"allOf":[{"$ref":"KBDocumentSitemapPatterns"}]} |
sync | {"nullable":true,"allOf":[{"$ref":"KBDocumentSitemapSync"}]} |
KBDocumentSitemapPatterns
{"type":"object"}
| Property | Definition |
|---|---|
include · required | {"type":"array","items":{"type":"string"}} |
exclude · required | {"type":"array","items":{"type":"string"}} |
KBDocumentSitemapSync
{"type":"object"}
| Property | Definition |
|---|---|
syncedAt · required | {"type":"string"} |
startedAt | {"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"} |
addedCount · required | {"type":"number"} |
removedCount · required | {"type":"number"} |
failure | {"nullable":true,"type":"object","properties":{"message":{"type":"string"},"at":{"type":"string"},"code":{"allOf":[{"$ref":"KBDocumentSitemapSyncFailureCode"}]}},"required":["message","at"]} |
KBDocumentSitemapSyncFailureCode
{"type":"string","enum":["documentLimit","integrationDisconnected","integrationUnauthorized","integrationAccountChanged","rateLimited"],"x-enumNames":["DOCUMENT_LIMIT","INTEGRATION_DISCONNECTED","INTEGRATION_UNAUTHORIZED","INTEGRATION_ACCOUNT_CHANGED","RATE_LIMITED"]}
KBDocumentTableData / Legacy9_KBDocumentTableData
{"type":"object"}
| Property | Definition |
|---|---|
type · required | {"type":"string","enum":["table"],"x-enumNames":["TABLE"]} |
name · required | {"type":"string"} |
rowsCount · required | {"type":"number"} |
url | {"nullable":true,"type":"string"} |
KBDocumentTextData / Legacy9_KBDocumentTextData
{"type":"object"}
| Property | Definition |
|---|---|
type · required | {"type":"string","enum":["text"],"x-enumNames":["TEXT"]} |
name · required | {"type":"string"} |
canEdit | {"type":"boolean"} |
url | {"nullable":true,"type":"string"} |
KBDocumentUrlData
{"type":"object"}
| Property | Definition |
|---|---|
type · required | {"type":"string","enum":["url"],"x-enumNames":["URL"]} |
name · required | {"type":"string"} |
url · required | {"type":"string"} |
title | {"type":"string"} |
refreshRate | {"allOf":[{"$ref":"KnowledgeBaseDocumentRefreshRate"}]} |
refreshTime | {"nullable":true,"type":"string","pattern":"^([01]\\d|2[0-3]):(00|30)$"} |
refreshTimezone | {"nullable":true,"type":"string"} |
lastSuccessUpdate | {"type":"string"} |
lastRefreshScheduledFor | {"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"} |
contentChangedAt | {"type":"string"} |
accessTokenID | {"type":"number"} |
integrationExternalID | {"type":"string"} |
source | {"allOf":[{"$ref":"KnowledgeBaseDocumentIntegrationType"}]} |
sitemapDocumentID | {"nullable":true,"type":"string"} |
integrationDocumentID | {"nullable":true,"type":"string"} |
integrationPath | {"nullable":true,"type":"array","items":{"type":"string"}} |
KBDocumentXLSXData / Legacy9_KBDocumentXLSXData
{"type":"object"}
| Property | Definition |
|---|---|
type · required | {"type":"string","enum":["xlsx"],"x-enumNames":["XLSX"]} |
name · required | {"type":"string"} |
rowsCount | {"type":"number"} |
url | {"nullable":true,"type":"string"} |
KnowledgeBaseDocumentIntegrationType
{"type":"string","enum":["zendesk","shopify","kustomer"],"x-enumNames":["ZENDESK","SHOPIFY","KUSTOMER"]}
KnowledgeBaseDocumentRefreshRate / Legacy9_KnowledgeBaseDocumentRefreshRate
{"type":"string","enum":["daily","weekly","monthly","never"],"x-enumNames":["DAILY","WEEKLY","MONTHLY","NEVER"]}
Legacy9_CompiledAgentKnowledgeBaseFilter
{"type":"object"}
| Property | Definition |
|---|---|
key · required | {"type":"string"} |
value · required | {"type":"string"} |
operator · required | {"$ref":"Legacy9_KBMetadataFilterOperation"} |
Legacy9_DocumentMetadataFields
{"type":"object"}
| Property | Definition |
|---|---|
key · required | {"type":"string"} |
values · required | {"type":"array","items":{"type":"string"}} |
Legacy9_KBDocumentData
{"oneOf":[{"$ref":"Legacy9_KBDocumentUrlData"},{"$ref":"Legacy9_KBDocumentDocxData"},{"$ref":"Legacy9_KBDocumentPDFData"},{"$ref":"Legacy9_KBDocumentTextData"},{"$ref":"Legacy9_KBDocumentMarkdownData"},{"$ref":"Legacy9_KBDocumentCSVData"},{"$ref":"Legacy9_KBDocumentXLSXData"},{"$ref":"Legacy9_KBDocumentTableData"}]}
Legacy9_KBDocumentUrlData
{"type":"object"}
| Property | Definition |
|---|---|
type · required | {"type":"string","enum":["url"],"x-enumNames":["URL"]} |
name · required | {"type":"string"} |
url · required | {"type":"string"} |
refreshRate | {"allOf":[{"$ref":"Legacy9_KnowledgeBaseDocumentRefreshRate"}]} |
lastSuccessUpdate | {"type":"string"} |
accessTokenID | {"type":"number"} |
integrationExternalID | {"type":"string"} |
source | {"allOf":[{"$ref":"Legacy9_KnowledgeBaseDocumentIntegrationType"}]} |
Legacy9_KBMetadataFilterOperation
{"type":"string","enum":["is","is_not","contains","not_contains"],"x-enumNames":["IS","IS_NOT","CONTAINS","NOT_CONTAINS"]}
Legacy9_KnowledgeBaseDocumentIntegrationType
{"type":"string","enum":["zendesk","shopify"],"x-enumNames":["ZENDESK","SHOPIFY"]}
StableKnowledgeBaseQueryRequest
{"type":"object","additionalProperties":false}
| Property | Definition |
|---|---|
version · required | Whether to query the draft or the published version of the knowledge base. {"type":"string","enum":["draft","published"],"x-enumNames":["DRAFT","PUBLISHED"]} |
filters | Metadata filters used to narrow down which document chunks are searched. {"type":"object","additionalProperties":{}} |
question · required | The natural-language question to ask the knowledge base. {"type":"string"} |
settings | {"allOf":[{"$ref":"StableKnowledgeBaseQuerySettings"}]} |
synthesis | Whether to synthesize an answer from the retrieved chunks; when false, only raw chunks are returned. {"type":"boolean"} |
chunkLimit | The maximum number of document chunks to retrieve. {"type":"integer","minimum":1,"maximum":30} |
instruction | An additional instruction applied when synthesizing the answer from the retrieved chunks. {"type":"string"} |
StableKnowledgeBaseQueryResponse
{"type":"object"}
| Property | Definition |
|---|---|
answer · required | The result of the knowledge base query, including the synthesized answer and token usage. {"type":"object","properties":{"model":{"type":"string","enum":["gpt-3.5-turbo-1106","gpt-3.5-turbo","gpt-4","gpt-4o","gpt-4o-mini","gpt-4.1-2025-04-14","gpt-4.1-mini-2025-04-14","gpt-4.1-nano-2025-04-14","gpt-o3-mini","o3-2025-04-16","o4-mini-2025-04-16","gpt-5","gpt-5-mini","gpt-5-nano","gpt-5.2","gpt-5.4","gpt-5.4-mini","gpt-5.5","gpt-5.6-sol","gpt-5.6-terra","gpt-5.6-luna","gpt-6-sol","gpt-6-luna","gpt-6.1-sol","gpt-realtime","gpt-live-1","claude-4-opus","claude-4-sonnet","claude-4.5-sonnet","claude-4.6-sonnet","claude-4.5-haiku","claude-4.5-opus","claude-4.7-opus","bedrock-claude-4-sonnet","bedrock-claude-4.5-sonnet","bedrock-claude-4.6-sonnet","bedrock-claude-5-sonnet","bedrock-claude-5.5-sonnet","bedrock-claude-4.5-haiku","bedrock-claude-5.5-haiku","bedrock-claude-4.5-opus","bedrock-claude-4.7-opus","bedrock-claude-4.8-opus","voiceflow-core-4.0","voiceflow-core-4.1","voiceflow-core-4.2","voiceflow-flash-4.2","gemini-2.5-pro","gemini-2.5-flash","gemini-live-2.5-flash","gemini-3-flash","gemini-3.5-flash","gemini-3.1-pro","gpt-oss-20b","gpt-oss-120b","llama-guard-4","llama-3.1-instant","llama-3.3-versatile","qwen3.6-27b","grok-4.6","voiceflow-flash-4.1","kimi-k3","gemini-flash-2","gpt-4-turbo","claude-3.5-haiku","claude-3-opus","claude-3.7-sonnet","claude-v2","llama-3.2-1b-preview","gemini-pro-1.5","claude-3-haiku","claude-3-sonnet","text-davinci-003","claude-v1","claude-instant-v1","deep-seek-r1-distill-llama-70B","claude-3.5-sonnet"],"description":"The AI model used to answer the query.","x-enumNames":["GPT_3_5_TURBO_1106","GPT_3_5_TURBO","GPT_4","GPT_4_O","GPT_4_O_MINI","GPT_4_1","GPT_4_1_MINI","GPT_4_1_NANO","GPT_O_3_MINI","GPT_O_3","GPT_O_4_MINI","GPT_5","GPT_5_MINI","GPT_5_NANO","GPT_5_2","GPT_5_4","GPT_5_4_MINI","GPT_5_5","GPT_5_6_SOL","GPT_5_6_TERRA","GPT_5_6_LUNA","GPT_6_SOL","GPT_6_LUNA","GPT_6_1_SOL","GPT_REALTIME","GPT_LIVE_1","CLAUDE_4_OPUS","CLAUDE_4_SONNET","CLAUDE_4_5_SONNET","CLAUDE_4_6_SONNET","CLAUDE_4_5_HAIKU","CLAUDE_4_5_OPUS","CLAUDE_4_7_OPUS","BEDROCK_CLAUDE_4_SONNET","BEDROCK_CLAUDE_4_5_SONNET","BEDROCK_CLAUDE_4_6_SONNET","BEDROCK_CLAUDE_5_SONNET","BEDROCK_CLAUDE_5_5_SONNET","BEDROCK_CLAUDE_4_5_HAIKU","BEDROCK_CLAUDE_5_5_HAIKU","BEDROCK_CLAUDE_4_5_OPUS","BEDROCK_CLAUDE_4_7_OPUS","BEDROCK_CLAUDE_4_8_OPUS","VOICEFLOW_CORE_4_0","VOICEFLOW_CORE_4_1","VOICEFLOW_CORE_4_2","VOICEFLOW_FLASH_4_2","GEMINI_2_5_PRO","GEMINI_2_5_FLASH","GEMINI_LIVE_2_5_FLASH","GEMINI_3_FLASH","GEMINI_3_5_FLASH","GEMINI_3_1_PRO","GPT_OSS_20_B","GPT_OSS_120_B","LLAMA_GUARD_4","LLAMA_3_1_INSTANT","LLAMA_3_3_VERSATILE","QWEN_3_6_27_B","GROK_4_6","VOICEFLOW_FLASH_4_1","KIMI_K_3","GEMINI_FLASH_2","GPT_4_TURBO","CLAUDE_3_5_HAIKU","CLAUDE_3_OPUS","CLAUDE_3_7_SONNET","CLAUDE_V_2","LLAMA_3_2_1_B_PREVIEW","GEMINI_PRO_1_5","CLAUDE_3_HAIKU","CLAUDE_3_SONNET","DA_VINCI_003","CLAUDE_V_1","CLAUDE_INSTANT_V_1","DEEP_SEEK_R_1_DISTILL_LLAMA_70_B","CLAUDE_3_5_SONNET"]},"output":{"nullable":true,"description":"The synthesized answer text, or `null` when no answer was generated.","type":"string"},"tokens":{"type":"number","description":"The total number of tokens consumed by the query."},"duration":{"type":"number","description":"The time it took to execute the query."},"queryTokens":{"type":"number","description":"The number of input tokens consumed by the query, after multipliers."},"answerTokens":{"type":"number","description":"The number of output tokens consumed by the answer, after multipliers."},"inputMultiplier":{"type":"number","description":"The billing multiplier applied to input tokens."},"cacheMultiplier":{"type":"number","description":"The billing multiplier applied to cached input tokens."},"outputMultiplier":{"type":"number","description":"The billing multiplier applied to output tokens."},"cacheWriteTokens":{"type":"number","description":"The number of input tokens written to the prompt cache."},"queryCachedTokens":{"type":"number","description":"The number of input tokens read from the prompt cache."},"cacheWriteMultiplier":{"type":"number","description":"The billing multiplier applied to cache-write tokens."},"queryRemainderTokens":{"type":"number","description":"The number of input tokens that were not served from the prompt cache."},"base":{"type":"object","properties":{"queryTokens":{"type":"number","description":"The raw number of input tokens consumed by the query."},"answerTokens":{"type":"number","description":"The raw number of output tokens consumed by the answer."},"cacheWriteTokens":{"type":"number","description":"The raw number of input tokens written to the prompt cache."},"queryCachedTokens":{"type":"number","description":"The raw number of input tokens read from the prompt cache."}},"required":["queryTokens","answerTokens","cacheWriteTokens","queryCachedTokens"],"description":"The raw token counts before billing multipliers are applied."},"priorityMultipliers":{"description":"The billing multipliers applied when the query runs with priority processing.","type":"object","properties":{"inputMultiplier":{"type":"number","description":"The priority billing multiplier applied to input tokens."},"cacheMultiplier":{"type":"number","description":"The priority billing multiplier applied to cached input tokens."},"outputMultiplier":{"type":"number","description":"The priority billing multiplier applied to output tokens."},"cacheWriteMultiplier":{"type":"number","description":"The priority billing multiplier applied to cache-write tokens."}},"required":["inputMultiplier","cacheMultiplier","outputMultiplier","cacheWriteMultiplier"]},"chunks":{"type":"array","items":{"type":"object","properties":{"score":{"type":"number"},"chunkID":{"type":"string"},"documentID":{"type":"string"},"content":{"type":"string"},"source":{"$ref":"KBDocumentData"},"metadata":{"type":"object","additionalProperties":{}}},"required":["score","chunkID","documentID","content","source","metadata"]}}},"required":["model","output","tokens","duration","queryTokens","answerTokens","inputMultiplier","cacheMultiplier","outputMultiplier","cacheWriteTokens","queryCachedTokens","cacheWriteMultiplier","queryRemainderTokens","base","chunks"]} |
StableKnowledgeBaseQuerySettings
{"type":"object"}
| Property | Definition |
|---|---|
model | The AI model used to synthesize the answer. {"type":"string","enum":["gpt-3.5-turbo-1106","gpt-3.5-turbo","gpt-4","gpt-4o","gpt-4o-mini","gpt-4.1-2025-04-14","gpt-4.1-mini-2025-04-14","gpt-4.1-nano-2025-04-14","gpt-o3-mini","o3-2025-04-16","o4-mini-2025-04-16","gpt-5","gpt-5-mini","gpt-5-nano","gpt-5.2","gpt-5.4","gpt-5.4-mini","gpt-5.5","gpt-5.6-sol","gpt-5.6-terra","gpt-5.6-luna","gpt-6-sol","gpt-6-luna","gpt-6.1-sol","gpt-realtime","gpt-live-1","claude-4-opus","claude-4-sonnet","claude-4.5-sonnet","claude-4.6-sonnet","claude-4.5-haiku","claude-4.5-opus","claude-4.7-opus","bedrock-claude-4-sonnet","bedrock-claude-4.5-sonnet","bedrock-claude-4.6-sonnet","bedrock-claude-5-sonnet","bedrock-claude-5.5-sonnet","bedrock-claude-4.5-haiku","bedrock-claude-5.5-haiku","bedrock-claude-4.5-opus","bedrock-claude-4.7-opus","bedrock-claude-4.8-opus","voiceflow-core-4.0","voiceflow-core-4.1","voiceflow-core-4.2","voiceflow-flash-4.2","gemini-2.5-pro","gemini-2.5-flash","gemini-live-2.5-flash","gemini-3-flash","gemini-3.5-flash","gemini-3.1-pro","gpt-oss-20b","gpt-oss-120b","llama-guard-4","llama-3.1-instant","llama-3.3-versatile","qwen3.6-27b","grok-4.6","voiceflow-flash-4.1","kimi-k3","gemini-flash-2","gpt-4-turbo","claude-3.5-haiku","claude-3-opus","claude-3.7-sonnet","claude-v2","llama-3.2-1b-preview","gemini-pro-1.5","claude-3-haiku","claude-3-sonnet","text-davinci-003","claude-v1","claude-instant-v1","deep-seek-r1-distill-llama-70B","claude-3.5-sonnet"],"x-enumNames":["GPT_3_5_TURBO_1106","GPT_3_5_TURBO","GPT_4","GPT_4_O","GPT_4_O_MINI","GPT_4_1","GPT_4_1_MINI","GPT_4_1_NANO","GPT_O_3_MINI","GPT_O_3","GPT_O_4_MINI","GPT_5","GPT_5_MINI","GPT_5_NANO","GPT_5_2","GPT_5_4","GPT_5_4_MINI","GPT_5_5","GPT_5_6_SOL","GPT_5_6_TERRA","GPT_5_6_LUNA","GPT_6_SOL","GPT_6_LUNA","GPT_6_1_SOL","GPT_REALTIME","GPT_LIVE_1","CLAUDE_4_OPUS","CLAUDE_4_SONNET","CLAUDE_4_5_SONNET","CLAUDE_4_6_SONNET","CLAUDE_4_5_HAIKU","CLAUDE_4_5_OPUS","CLAUDE_4_7_OPUS","BEDROCK_CLAUDE_4_SONNET","BEDROCK_CLAUDE_4_5_SONNET","BEDROCK_CLAUDE_4_6_SONNET","BEDROCK_CLAUDE_5_SONNET","BEDROCK_CLAUDE_5_5_SONNET","BEDROCK_CLAUDE_4_5_HAIKU","BEDROCK_CLAUDE_5_5_HAIKU","BEDROCK_CLAUDE_4_5_OPUS","BEDROCK_CLAUDE_4_7_OPUS","BEDROCK_CLAUDE_4_8_OPUS","VOICEFLOW_CORE_4_0","VOICEFLOW_CORE_4_1","VOICEFLOW_CORE_4_2","VOICEFLOW_FLASH_4_2","GEMINI_2_5_PRO","GEMINI_2_5_FLASH","GEMINI_LIVE_2_5_FLASH","GEMINI_3_FLASH","GEMINI_3_5_FLASH","GEMINI_3_1_PRO","GPT_OSS_20_B","GPT_OSS_120_B","LLAMA_GUARD_4","LLAMA_3_1_INSTANT","LLAMA_3_3_VERSATILE","QWEN_3_6_27_B","GROK_4_6","VOICEFLOW_FLASH_4_1","KIMI_K_3","GEMINI_FLASH_2","GPT_4_TURBO","CLAUDE_3_5_HAIKU","CLAUDE_3_OPUS","CLAUDE_3_7_SONNET","CLAUDE_V_2","LLAMA_3_2_1_B_PREVIEW","GEMINI_PRO_1_5","CLAUDE_3_HAIKU","CLAUDE_3_SONNET","DA_VINCI_003","CLAUDE_V_1","CLAUDE_INSTANT_V_1","DEEP_SEEK_R_1_DISTILL_LLAMA_70_B","CLAUDE_3_5_SONNET"]} |
system | The system prompt applied to the model when synthesizing the answer. {"type":"string"} |
maxTokens | Deprecated. The model's default output limit applies when this is lower or unset, and the model's maximum caps it. {"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991} |
temperature | The sampling temperature applied to the model when synthesizing the answer. {"type":"number"} |
reasoningEffort | The reasoning effort applied to the model when synthesizing the answer. {"type":"string","enum":["off","adaptive","minimal","low","medium","high"],"x-enumNames":["OFF","ADAPTIVE","MINIMAL","LOW","MEDIUM","HIGH"]} |
Was this page helpful?
Thanks for your feedback.