curl --request POST \
--url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({query: '<string>'})
};
fetch('https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/search"
payload = { "query": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"object": "list",
"data": [
{
"document_id": "<string>",
"source_type": "uploaded_file",
"source_url": "<string>",
"score": 123,
"content": [
{
"type": "text",
"text": "<string>"
}
],
"filename": "<string>",
"native_file_id": "<string>",
"native_file_workspace_id": "<string>",
"attributes": {
"page": 123,
"chunk_index": 123,
"scope": "knowledge",
"conversation_id": "<string>"
}
}
]
}Semantic search
Hits are enriched from document rows directly (no registry
join). They carry document_id + display source_url only - never
fetch_url, never tokens. Resolve downloadable links lazily
via GET /documents/{document_id}/source_url. Requires reader+.
curl --request POST \
--url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({query: '<string>'})
};
fetch('https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/search"
payload = { "query": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"object": "list",
"data": [
{
"document_id": "<string>",
"source_type": "uploaded_file",
"source_url": "<string>",
"score": 123,
"content": [
{
"type": "text",
"text": "<string>"
}
],
"filename": "<string>",
"native_file_id": "<string>",
"native_file_workspace_id": "<string>",
"attributes": {
"page": 123,
"chunk_index": 123,
"scope": "knowledge",
"conversation_id": "<string>"
}
}
]
}Authorizations
User session JWT or instance API key (iak_*). Send as Authorization: Bearer <token>.
Path Parameters
Knowledge base id. Legacy physical prefix vs_ (the kb_ rename is deferred).
128^vs_[A-Za-z0-9-]+$Body
81921 <= x <= 50Drop hits below this score.
Structured filter AST validated at the API boundary; provider
adapters transform it into provider DSL internally. Invalid
filters are rejected with 400 VALIDATION_ERROR, never
silently coerced. Nesting capped at 8 levels; total leaf
clauses at 100.
- Option 1
- Option 2
- Option 3
- Option 4
Hide child attributes
Hide child attributes
eq, ne, in, nin, gt, gte, lt, lte, exists, matches Dot-path filter. Currently only tags.<key> is
supported; metadata.*, source_type, web_source_id and
origin are not yet implemented and return
400 INVALID_FILTER_FIELD.
256Operator-dependent. Scalars for eq/ne/comparisons;
arrays for in/nin; boolean for exists; string for
matches.
Restrict to a scope. Omit for both.
knowledge, conversation Required when scope: conversation.
Response
Search results, best score first.
list Hide child attributes
Hide child attributes
^vsf_[A-Za-z0-9-]+$uploaded_file, remote_file, web_page, connector_document Display/provenance URL for the hit. May be null - some
uploaded files carry no display URL, and legacy web rows may
have none. fetch_url and tokens never appear in hits;
obtain a downloadable link lazily via the single
(GET .../documents/{document_id}/source_url) or batch
(POST .../source_urls) resolver.
Platform-native file id when source_type: uploaded_file,
null otherwise. Pass it (with native_file_workspace_id) to
the batch or single citation resolver to mint a downloadable
link.
Workspace owning the native file. Defaults to the caller's workspace; a foreign value means the source can only be resolved from its owning workspace.
Was this page helpful?