---
title: "Retrieve contexts from chosen knowledge base"
method: POST
path: "/serverless/v1/knowledge/retrieve"
tags: ["Serverless.Knowledge"]
---

# Retrieve contexts from chosen knowledge base

`POST /serverless/v1/knowledge/retrieve`

## Request

- Base URL: `https://api.friendli.ai`
- URL: `https://api.friendli.ai/serverless/v1/knowledge/retrieve`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/friendli/apis/friendli-suite-api-reference/docs/serverless/v1/knowledge/retrieve/post.ts> (a function with typed inputs; its response is checked against the schema)

Retrieve related documents from knowledge base by similarity.

## Headers

- `X-Friendli-Team` string, nullable: ID of team to run requests as (optional parameter).

## Request body

- ServerlessKnowledgeRetrievalBody: Knowledge retrieval request.
  - `query` string, required: A text string used to find relevant information within the knowledge-base.
  - `k` integer, required: Maximum number of top-ranked knowledge-base entries to return in results.
  - `knowledgeIds` string[], required: A List of knowledge-base IDs. For now, only one knowledge-base is supported.

## Response `200`

Successful Response

- ServerlessKnowledgeRetrievalSuccess: Knowledge retrieval response.
  - `results` KnowledgeRetrievedChunk[], required: A list of result.
    - `text` string, required: Retrieved text matching the search query.
    - `score` number, required: Numerical relevance score of the retrieved result.
    - `contentChunkId` string, required: ID of specific text segment.
    - `contentId` string, required: ID of content in knowledge-base.

## Other responses

- `400`: Bad Request
- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/friendli/apis/friendli-suite-api-reference.md) - [All operations](https://skmtc.dev/friendli/apis/friendli-suite-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/friendli/apis/friendli-suite-api-reference/revisions/38fb43993a11?raw)