Semantic search

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_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,
        "conversation_id": "<string>"
      }
    }
  ]
}

POST

knowledge_bases

{knowledgeBaseId}

Semantic search

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_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,
        "conversation_id": "<string>"
      }
    }
  ]
}

Authorizations

Authorization

string

header

required

User session JWT or instance API key (iak_*). Send as Authorization: Bearer <token>.

Path Parameters

knowledgeBaseId

string

required

Knowledge base id. Legacy physical prefix vs_ (the kb_ rename is deferred).

Maximum string length: 128

Pattern: ^vs_[A-Za-z0-9-]+$

Body

application/json

query

string

required

Maximum string length: 8192

limit

integer

default:10

Required range: 1 <= x <= 50

min_score

number

Drop hits below this score.

filter

object

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

filter.op

enum<string>

required

Available options:

eq,

ne,

in,

nin,

gt,

gte,

lt,

lte,

exists,

matches

filter.field

string

required

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.

Maximum string length: 256

filter.value

any

required

Operator-dependent. Scalars for eq/ne/comparisons; arrays for in/nin; boolean for exists; string for matches.

scope

enum<string>

Restrict to a scope. Omit for both.

Available options:

knowledge,

conversation

conversation_id

string

Required when scope: conversation.

Response

Search results, best score first.

object

enum<string>

required

Available options:

list

data

object[]

required

Hide child attributes

data.document_id

string

required

Pattern: ^vsf_[A-Za-z0-9-]+$

data.source_type

enum<string>

required

Available options:

uploaded_file,

remote_file,

web_page,

connector_document

data.source_url

string<uri> | null

required

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.

data.score

number

required

data.content

object[]

required

Hide child attributes

data.content.type

enum<string>

required

Available options:

text

data.content.text

string

required

data.filename

string | null

data.native_file_id

string | null

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.

data.native_file_workspace_id

string | null

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.

data.attributes

object

Hide child attributes

data.attributes.page

integer | null

data.attributes.chunk_index

integer

data.attributes.scope

enum<string>

Available options:

knowledge,

conversation

data.attributes.conversation_id

string | null

Update seed configuration List access bindings

⌘I

Introduction

Platform API

Agent Creator API

LLM Gateway API

Governance API

Knowledges API

Semantic search

Authorizations

Path Parameters

Body

Response