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

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


## OpenAPI

````yaml post /orgs/{org_id}/search/retrieve
openapi: 3.1.0
info:
  title: Flow API
  description: Content-addressing backend with Git-like versioning
  version: 1.0.0
servers:
  - url: https://api.yertle.com
    description: Production
security: []
paths:
  /orgs/{org_id}/search/retrieve:
    post:
      tags:
        - search
      summary: Retrieve Subgraph
      description: |-
        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.
      operationId: retrieve_subgraph_orgs__org_id__search_retrieve_post
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Org Id
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    RetrieveRequest:
      properties:
        query:
          type: string
          title: Query
          description: Natural-language query or keywords
        top_k:
          anyOf:
            - type: integer
              maximum: 50
              minimum: 1
            - type: 'null'
          title: Top K
          description: Number of entry-point matches before graph expansion
          default: 5
        expansion_depth:
          anyOf:
            - type: string
              enum:
                - none
                - shallow
                - standard
                - deep
            - type: 'null'
          title: Expansion Depth
          description: >-
            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.
          default: none
        scope:
          anyOf:
            - $ref: '#/components/schemas/RetrievalScopeRequest'
            - type: 'null'
          description: Optional scope filters
        include_raw_text:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Include Raw Text
          description: Return the prose text_content per node (for debugging / eval)
          default: false
      type: object
      required:
        - query
      title: RetrieveRequest
      description: |-
        Request body for POST /orgs/{org_id}/search/retrieve.

        See docs/notes/features/rag/RETRIEVAL_API_PLAN.md for the
        full API design.
    RetrieveResponse:
      properties:
        query:
          type: string
          title: Query
        matches:
          items:
            $ref: '#/components/schemas/SubgraphMatch'
          type: array
          title: Matches
        nodes:
          items:
            $ref: '#/components/schemas/SubgraphNode'
          type: array
          title: Nodes
        connections:
          items:
            $ref: '#/components/schemas/SubgraphConnection'
          type: array
          title: Connections
      type: object
      required:
        - query
        - matches
        - nodes
        - connections
      title: RetrieveResponse
      description: Response for POST /orgs/{org_id}/search/retrieve.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RetrievalScopeRequest:
      properties:
        root_node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Root Node Id
          description: Restrict matches to this node and its descendants
        tag_filters:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Tag Filters
          description: Pre-filter matches by tag key/value (intersection semantics)
        directory_prefix:
          anyOf:
            - type: string
            - type: 'null'
          title: Directory Prefix
          description: Restrict matches to nodes whose directory starts with this prefix
      type: object
      title: RetrievalScopeRequest
      description: Optional scope filters for graph-aware retrieval.
    SubgraphMatch:
      properties:
        node_id:
          type: string
          title: Node Id
          description: Matched node UUID
        title:
          type: string
          title: Title
          description: Matched node title
        score:
          type: number
          title: Score
          description: Pass-1 ranker score
        match_reason:
          type: string
          enum:
            - fts
            - vector
            - hybrid
          title: Match Reason
          description: Which Pass-1 branch produced this hit
          default: fts
      type: object
      required:
        - node_id
        - title
        - score
      title: SubgraphMatch
      description: An entry-point hit from Pass 1 (FTS today; hybrid later).
    SubgraphNode:
      properties:
        node_id:
          type: string
          title: Node Id
        title:
          type: string
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        path:
          items:
            type: string
          type: array
          title: Path
          description: Ancestry path of titles, root → leaf
        tags:
          additionalProperties:
            type: string
          type: object
          title: Tags
        directories:
          items:
            type: string
          type: array
          title: Directories
        text_content:
          anyOf:
            - type: string
            - type: 'null'
          title: Text Content
          description: Prose text_content (only when include_raw_text=true)
      type: object
      required:
        - node_id
        - title
      title: SubgraphNode
      description: A node in the expanded subgraph response.
    SubgraphConnection:
      properties:
        connection_id:
          type: string
          title: Connection Id
        from_node_id:
          type: string
          title: From Node Id
        from_title:
          type: string
          title: From Title
        to_node_id:
          type: string
          title: To Node Id
        to_title:
          type: string
          title: To Title
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
        connection_type:
          type: string
          title: Connection Type
          default: default
      type: object
      required:
        - connection_id
        - from_node_id
        - from_title
        - to_node_id
        - to_title
      title: SubgraphConnection
      description: An edge between two nodes in the expanded subgraph.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````