API Reference

Retrieve

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Retrieve from Knowledge Base

retrieve.documents(strknowledge_base_id, RetrieveDocumentsParams**kwargs) -> RetrieveDocumentsResponse

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

ParametersExpand Collapse

knowledge_base_id: str

formatuuid

num_results: int

Number of results to return

minimum1

maximum100

query: str

The search query text

minLength1

alpha: Optional[float]

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[Filters]

Metadata filters to apply to the search

must: Optional[Iterable[FiltersMust]]

All conditions must match (AND)

field: str

Metadata field name

operator: Literal["eq", "ne", "gt", 6 more]

Comparison operator

Accepts one of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

"in"

"not_in"

"contains"

value: Union[str, float, bool, SequenceNotStr[str]]

Value to compare against (type depends on field)

Accepts one of the following:

FiltersMustValueUnionMember0 = str

FiltersMustValueUnionMember1 = float

FiltersMustValueUnionMember2 = bool

FiltersMustValueUnionMember3 = SequenceNotStr[str]

must_not: Optional[Iterable[FiltersMustNot]]

No conditions should match (NOT)

field: str

Metadata field name

operator: Literal["eq", "ne", "gt", 6 more]

Comparison operator

Accepts one of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

"in"

"not_in"

"contains"

value: Union[str, float, bool, SequenceNotStr[str]]

Value to compare against (type depends on field)

Accepts one of the following:

FiltersMustNotValueUnionMember0 = str

FiltersMustNotValueUnionMember1 = float

FiltersMustNotValueUnionMember2 = bool

FiltersMustNotValueUnionMember3 = SequenceNotStr[str]

should: Optional[Iterable[FiltersShould]]

At least one condition must match (OR)

field: str

Metadata field name

operator: Literal["eq", "ne", "gt", 6 more]

Comparison operator

Accepts one of the following:

"eq"

"ne"

"gt"

"gte"

"lt"

"lte"

"in"

"not_in"

"contains"

value: Union[str, float, bool, SequenceNotStr[str]]

Value to compare against (type depends on field)

Accepts one of the following:

FiltersShouldValueUnionMember0 = str

FiltersShouldValueUnionMember1 = float

FiltersShouldValueUnionMember2 = bool

FiltersShouldValueUnionMember3 = SequenceNotStr[str]

ReturnsExpand Collapse

class RetrieveDocumentsResponse: …

results: List[Result]

Array of retrieved document chunks

metadata: Dict[str, object]

Metadata associated with the document

text_content: str

The text content of the document chunk

total_results: int

Number of results returned

Retrieve from Knowledge Base

Python

HTTP

TypeScript

Python

from gradient import Gradient

client = Gradient()
response = client.retrieve.documents(
    knowledge_base_id="550e8400-e29b-41d4-a716-446655440000",
    num_results=5,
    query="What are the best practices for deploying machine learning models?",
)
print(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
}