Skip to main content
POST
/
v1
/
retrieval
Get context
curl --request POST \
  --url http://localhost:4000/v1/retrieval \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "workspaceId": "ws_123e4567-e89b-12d3-a456-426614174000",
  "knowledgeGraphId": "kg_681c0068-b589-4923-ac4a-73040fab7a45",
  "prompt": "Give me the following information regarding Harry Potter. 1) Who is he?, 2) What is his relationship with Gryffindor Inc., Weasleys Wizard Wheezes, and Ollivanders?",
  "limit": 5,
  "depth": 1,
  "rerank": true
}'
{
  "data": [
    "*Harry Potter -> Gryffindor Inc. (works_at)*: Harry Potter works at Gryffindor Inc. as Project Lead.",
    "*Harry Potter*: Harry Potter is a contact with email harry@gryffindor.com; he entered the system on 2025-09-01, had first outreach on 2025-08-11, was last contacted on 2025-08-28, and is in the lead lifecycle stage.",
    "*Harry Potter -> Weasleys Wizard Wheezes (advisor_to)*: Harry Potter is advising Weasleys Wizard Wheezes on new product launches.",
    "*Weasleys Wizard Wheezes*: Weasleys Wizard Wheezes is a magical joke shop company co-founded by Fred and George Weasley, specializing in prank and novelty products for wizarding customers.",
    "*Harry Potter -> Ollivanders (consulted_for)*: Harry Potter consulted for Ollivanders regarding wand customization strategies.",
    "*Ollivanders*: Ollivanders is a wand-making company with a legacy spanning centuries, providing premium wands to witches and wizards globally."
  ]
}
This endpoint retrieves relevant context from your knowledge graph based on a textual prompt. Understanding how the system processes your prompt is critical to achieving best-in-class results.
  1. Similarity search: The knowledge graph is first searched to find nodes that are most similar to the prompt. This ensures that only the most relevant information is considered for retrieval.
  2. Optional reranking: If rerank is enabled, the system also analyzes the prompt for example for bullet points or enumerated instructions (e.g., “1) Look at this, 2) Include this as well, 3) This is also important”). These bullets are used to rerank the retrieved nodes so that the final context better reflects the user’s priorities and instructions.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
workspaceId
string
required

The id of the workspace that the context vault belongs to.

Example:

"ws_123e4567-e89b-12d3-a456-426614174000"

​
knowledgeGraphId
string
required

The id of the vault from which to retrieve context.

Example:

"kg_681c0068-b589-4923-ac4a-73040fab7a45"

​
prompt
string
required

The prompt to retrieve context for.

Example:

"Give me the following information regarding Harry Potter. 1) Who is he?, 2) What is his relationship with Gryffindor Inc., Weasleys Wizard Wheezes, and Ollivanders?"

​
limit
number
required

Number of nodes to consider at the first level of the knowledge vault.

Example:

5

​
depth
number
required

Depth of nodes to retrieve from the graph.

Example:

1

​
rerank
boolean
required

Whether to rerank results for relevance.

Example:

true

Response

Context successfully retrieved

​
data
string[]
required

The retrieved and relevant context.

Example:
[
  "*Harry Potter -> Gryffindor Inc. (works_at)*: Harry Potter works at Gryffindor Inc. as Project Lead.",
  "*Harry Potter*: Harry Potter is a contact with email harry@gryffindor.com; he entered the system on 2025-09-01, had first outreach on 2025-08-11, was last contacted on 2025-08-28, and is in the lead lifecycle stage.",
  "*Harry Potter -> Weasleys Wizard Wheezes (advisor_to)*: Harry Potter is advising Weasleys Wizard Wheezes on new product launches.",
  "*Weasleys Wizard Wheezes*: Weasleys Wizard Wheezes is a magical joke shop company co-founded by Fred and George Weasley, specializing in prank and novelty products for wizarding customers.",
  "*Harry Potter -> Ollivanders (consulted_for)*: Harry Potter consulted for Ollivanders regarding wand customization strategies.",
  "*Ollivanders*: Ollivanders is a wand-making company with a legacy spanning centuries, providing premium wands to witches and wizards globally."
]
⌘I