Retrieve Subgraph

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.

POST /orgs/{org_id}/search/retrieve

Retrieve Subgraph

cURL

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
}
'

200

{
  "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"
    }
  ]
}

Headers

authorization · string | null

Path Parameters

org_id · string<uuid> · required

Body

application/json

Request body for POST /orgs/{org_id}/search/retrieve.

See docs/notes/features/rag/RETRIEVAL_API_PLAN.md for the full API design.

query · string · required

Natural-language query or keywords

top_k · integer | null · default: 5

Number of entry-point matches before graph expansion

Required range: 1 <= x <= 50

expansion_depth · enum<string> | null · default: none

How 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.

Available options: none, shallow, standard, deep

scope · RetrievalScopeRequest · object

Optional scope filters

Show child attributes

include_raw_text · boolean | null · default: false

Return the prose text_content per node (for debugging / eval)

Response

200

application/json

Successful Response

Response for POST /orgs/{org_id}/search/retrieve.

query · string · required

matches · SubgraphMatch · object[] · required

Show child attributes

nodes · SubgraphNode · object[] · required

Show child attributes

connections · SubgraphConnection · object[] · required

Show child attributes