API Reference

Retrieve

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Retrieve from Knowledge Base

post/{knowledgeBaseId}/retrieve

Retrieve relevant documents from a knowledge base using semantic search.

This endpoint:

1. Authenticates the request using the provided bearer token
2. Generates embeddings for the query using the knowledge base's configured model
3. Performs vector similarity search in the knowledge base
4. Returns the most relevant document chunks

Path ParametersExpand Collapse

knowledgeBaseId: string

formatuuid

Body ParametersExpand Collapse

num_results: number

Number of results to return

minimum1

maximum100

query: string

The search query text

minLength1

alpha: optional number

Weight for hybrid search (0-1):

• 0 = pure keyword search (BM25)
• 1 = pure vector search (default)
• 0.5 = balanced hybrid search

formatdouble

minimum0

maximum1

filters: optional object { must, must_not, should }

Metadata filters to apply to the search

must: optional array of object { field, operator, value }

All conditions must match (AND)

field: string

Metadata field name

operator: "eq" or "ne" or "gt" or 6 more

Comparison operator

Accepts one of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

"in"

"not_in"

"contains"

value: string or number or boolean or array of string

Value to compare against (type depends on field)

Accepts one of the following:

UnionMember0 = string

UnionMember1 = number

UnionMember2 = boolean

UnionMember3 = array of string

must_not: optional array of object { field, operator, value }

No conditions should match (NOT)

field: string

Metadata field name

operator: "eq" or "ne" or "gt" or 6 more

Comparison operator

Accepts one of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

"in"

"not_in"

"contains"

value: string or number or boolean or array of string

Value to compare against (type depends on field)

Accepts one of the following:

UnionMember0 = string

UnionMember1 = number

UnionMember2 = boolean

UnionMember3 = array of string

should: optional array of object { field, operator, value }

At least one condition must match (OR)

field: string

Metadata field name

operator: "eq" or "ne" or "gt" or 6 more

Comparison operator

Accepts one of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

"in"

"not_in"

"contains"

value: string or number or boolean or array of string

Value to compare against (type depends on field)

Accepts one of the following:

UnionMember0 = string

UnionMember1 = number

UnionMember2 = boolean

UnionMember3 = array of string

ReturnsExpand Collapse

results: array of object { metadata, text_content }

Array of retrieved document chunks

metadata: map[unknown]

Metadata associated with the document

text_content: string

The text content of the document chunk

total_results: number

Number of results returned

Retrieve from Knowledge Base

HTTP

HTTP

TypeScript

Python

curl https://kbaas.do-ai.run/v1/$KNOWLEDGE_BASE_ID/retrieve \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $DIGITALOCEAN_ACCESS_TOKEN" \
    -d '{
          "num_results": 5,
          "query": "What are the best practices for deploying machine learning models?",
          "alpha": 0.75
        }'

200 example

{
  "results": [
    {
      "metadata": {
        "source": "bar",
        "page": "bar",
        "category": "bar",
        "timestamp": "bar"
      },
      "text_content": "Machine learning models should be deployed with proper monitoring and versioning..."
    }
  ],
  "total_results": 5
}

Returns Examples

200 example

{
  "results": [
    {
      "metadata": {
        "source": "bar",
        "page": "bar",
        "category": "bar",
        "timestamp": "bar"
      },
      "text_content": "Machine learning models should be deployed with proper monitoring and versioning..."
    }
  ],
  "total_results": 5
}