API Reference

Retrieve

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Retrieve from Knowledge Base

client.Retrieve.Documents(ctx, knowledgeBaseID, body) (*RetrieveDocumentsResponse, error)

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

The search supports hybrid search combining:

• Vector similarity (semantic search)
• Keyword matching (BM25)
• Custom metadata filters

ParametersExpand Collapse

knowledgeBaseID string

formatuuid

body RetrieveDocumentsParams

NumResults param.Field[int64]

Number of results to return

minimum1

maximum100

Query param.Field[string]

The search query text

minLength1

Alpha param.Field[float64]optional

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 param.Field[RetrieveDocumentsParamsFilters]optional

Metadata filters to apply to the search

Must []RetrieveDocumentsParamsFiltersMustoptional

All conditions must match (AND)

Field string

Metadata field name

Operator RetrieveDocumentsParamsFiltersMustOperator

Comparison operator

Accepts one of the following:

const RetrieveDocumentsParamsFiltersMustOperatorEq RetrieveDocumentsParamsFiltersMustOperator = "eq"

const RetrieveDocumentsParamsFiltersMustOperatorNe RetrieveDocumentsParamsFiltersMustOperator = "ne"

const RetrieveDocumentsParamsFiltersMustOperatorGt RetrieveDocumentsParamsFiltersMustOperator = "gt"

const RetrieveDocumentsParamsFiltersMustOperatorGte RetrieveDocumentsParamsFiltersMustOperator = "gte"

const RetrieveDocumentsParamsFiltersMustOperatorLt RetrieveDocumentsParamsFiltersMustOperator = "lt"

const RetrieveDocumentsParamsFiltersMustOperatorLte RetrieveDocumentsParamsFiltersMustOperator = "lte"

const RetrieveDocumentsParamsFiltersMustOperatorIn RetrieveDocumentsParamsFiltersMustOperator = "in"

const RetrieveDocumentsParamsFiltersMustOperatorNotIn RetrieveDocumentsParamsFiltersMustOperator = "not_in"

const RetrieveDocumentsParamsFiltersMustOperatorContains RetrieveDocumentsParamsFiltersMustOperator = "contains"

Value RetrieveDocumentsParamsFiltersMustValueUnion

Value to compare against (type depends on field)

Accepts one of the following:

UnionString

UnionFloat

UnionBool

type RetrieveDocumentsParamsFiltersMustValueArray []string

MustNot []RetrieveDocumentsParamsFiltersMustNotoptional

No conditions should match (NOT)

Field string

Metadata field name

Operator RetrieveDocumentsParamsFiltersMustNotOperator

Comparison operator

Accepts one of the following:

const RetrieveDocumentsParamsFiltersMustNotOperatorEq RetrieveDocumentsParamsFiltersMustNotOperator = "eq"

const RetrieveDocumentsParamsFiltersMustNotOperatorNe RetrieveDocumentsParamsFiltersMustNotOperator = "ne"

const RetrieveDocumentsParamsFiltersMustNotOperatorGt RetrieveDocumentsParamsFiltersMustNotOperator = "gt"

const RetrieveDocumentsParamsFiltersMustNotOperatorGte RetrieveDocumentsParamsFiltersMustNotOperator = "gte"

const RetrieveDocumentsParamsFiltersMustNotOperatorLt RetrieveDocumentsParamsFiltersMustNotOperator = "lt"

const RetrieveDocumentsParamsFiltersMustNotOperatorLte RetrieveDocumentsParamsFiltersMustNotOperator = "lte"

const RetrieveDocumentsParamsFiltersMustNotOperatorIn RetrieveDocumentsParamsFiltersMustNotOperator = "in"

const RetrieveDocumentsParamsFiltersMustNotOperatorNotIn RetrieveDocumentsParamsFiltersMustNotOperator = "not_in"

const RetrieveDocumentsParamsFiltersMustNotOperatorContains RetrieveDocumentsParamsFiltersMustNotOperator = "contains"

Value RetrieveDocumentsParamsFiltersMustNotValueUnion

Value to compare against (type depends on field)

Accepts one of the following:

UnionString

UnionFloat

UnionBool

type RetrieveDocumentsParamsFiltersMustNotValueArray []string

Should []RetrieveDocumentsParamsFiltersShouldoptional

At least one condition must match (OR)

Field string

Metadata field name

Operator RetrieveDocumentsParamsFiltersShouldOperator

Comparison operator

Accepts one of the following:

const RetrieveDocumentsParamsFiltersShouldOperatorEq RetrieveDocumentsParamsFiltersShouldOperator = "eq"

const RetrieveDocumentsParamsFiltersShouldOperatorNe RetrieveDocumentsParamsFiltersShouldOperator = "ne"

const RetrieveDocumentsParamsFiltersShouldOperatorGt RetrieveDocumentsParamsFiltersShouldOperator = "gt"

const RetrieveDocumentsParamsFiltersShouldOperatorGte RetrieveDocumentsParamsFiltersShouldOperator = "gte"

const RetrieveDocumentsParamsFiltersShouldOperatorLt RetrieveDocumentsParamsFiltersShouldOperator = "lt"

const RetrieveDocumentsParamsFiltersShouldOperatorLte RetrieveDocumentsParamsFiltersShouldOperator = "lte"

const RetrieveDocumentsParamsFiltersShouldOperatorIn RetrieveDocumentsParamsFiltersShouldOperator = "in"

const RetrieveDocumentsParamsFiltersShouldOperatorNotIn RetrieveDocumentsParamsFiltersShouldOperator = "not_in"

const RetrieveDocumentsParamsFiltersShouldOperatorContains RetrieveDocumentsParamsFiltersShouldOperator = "contains"

Value RetrieveDocumentsParamsFiltersShouldValueUnion

Value to compare against (type depends on field)

Accepts one of the following:

UnionString

UnionFloat

UnionBool

type RetrieveDocumentsParamsFiltersShouldValueArray []string

ReturnsExpand Collapse

type RetrieveDocumentsResponse struct{…}

Results []RetrieveDocumentsResponseResult

Array of retrieved document chunks

Metadata map[string, unknown]

Metadata associated with the document

TextContent string

The text content of the document chunk

TotalResults int64

Number of results returned

Retrieve from Knowledge Base

Go

HTTP

TypeScript

Python

Go

package main

import (
  "context"
  "fmt"

  "github.com/stainless-sdks/-go"
)

func main() {
  client := gradient.NewClient(

  )
  response, err := client.Retrieve.Documents(
    context.TODO(),
    "550e8400-e29b-41d4-a716-446655440000",
    gradient.RetrieveDocumentsParams{
      NumResults: gradient.F(int64(5)),
      Query: gradient.F("What are the best practices for deploying machine learning models?"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Results)
}

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
}