curl --request POST \
--url https://api.yertle.com/orgs/{org_id}/search/retrieve \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"top_k": 5,
"expansion_depth": "none",
"scope": {
"root_node_id": "<string>",
"tag_filters": {},
"directory_prefix": "<string>"
},
"include_raw_text": false
}
'{
"query": "<string>",
"matches": [
{
"node_id": "<string>",
"title": "<string>",
"score": 123,
"match_reason": "fts"
}
],
"nodes": [
{
"node_id": "<string>",
"title": "<string>",
"description": "<string>",
"path": [
"<string>"
],
"tags": {},
"directories": [
"<string>"
],
"text_content": "<string>"
}
],
"connections": [
{
"connection_id": "<string>",
"from_node_id": "<string>",
"from_title": "<string>",
"to_node_id": "<string>",
"to_title": "<string>",
"label": "<string>",
"connection_type": "default"
}
]
}Graph-aware retrieval — returns ranked node matches for a query, optionally with a surrounding subgraph.
Pass 1 (FTS today; hybrid when embeddings are enabled) finds entry-
point nodes. Pass 2 graph expansion is opt-in via expansion_depth:
the default "none" returns only the ranked matches; "shallow",
"standard", and "deep" progressively include children, parents,
and connection endpoints so agent callers get enough topology to
reason without N follow-up requests.
See docs/notes/features/rag/RETRIEVAL_API_PLAN.md.
curl --request POST \
--url https://api.yertle.com/orgs/{org_id}/search/retrieve \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"top_k": 5,
"expansion_depth": "none",
"scope": {
"root_node_id": "<string>",
"tag_filters": {},
"directory_prefix": "<string>"
},
"include_raw_text": false
}
'{
"query": "<string>",
"matches": [
{
"node_id": "<string>",
"title": "<string>",
"score": 123,
"match_reason": "fts"
}
],
"nodes": [
{
"node_id": "<string>",
"title": "<string>",
"description": "<string>",
"path": [
"<string>"
],
"tags": {},
"directories": [
"<string>"
],
"text_content": "<string>"
}
],
"connections": [
{
"connection_id": "<string>",
"from_node_id": "<string>",
"from_title": "<string>",
"to_node_id": "<string>",
"to_title": "<string>",
"label": "<string>",
"connection_type": "default"
}
]
}Documentation Index
Fetch the complete documentation index at: https://docs.yertle.com/llms.txt
Use this file to discover all available pages before exploring further.
Request body for POST /orgs/{org_id}/search/retrieve.
See docs/notes/features/rag/RETRIEVAL_API_PLAN.md for the full API design.
Natural-language query or keywords
Number of entry-point matches before graph expansion
1 <= x <= 50How aggressively Pass 2 walks the graph. 'none' (default) returns only the ranked matches with no graph expansion; 'shallow'/'standard'/'deep' progressively include children, parents, and connection endpoints.
none, shallow, standard, deep Optional scope filters
Show child attributes
Return the prose text_content per node (for debugging / eval)