> ## Documentation Index
> Fetch the complete documentation index at: https://wondeya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Probe an agent’s retrieval

> Runs the SAME hybrid retrieval a real conversation runs (the deterministic topic map plus the vector search, fused) and returns the passages the agent would have had, WITHOUT calling the model. Empty results mean the agent cannot answer that question yet.



## OpenAPI

````yaml /openapi.json post /v1/agents/{agentId}/query
openapi: 3.0.0
info:
  title: wondeya Developer API
  description: >-
    The public REST API for building on wondeya: agents, projects, pages,
    knowledge, assets, brand, theme, usage, retrieval and chat, authenticated by
    a workspace API key (`Authorization: Bearer wdy_live_…`).
  version: 0.1.0
  contact:
    name: wondeya
    url: https://wondeya.com
    email: team@wondeya.com
  license:
    name: Proprietary
    url: https://wondeya.com/terms
servers:
  - url: https://api.wondeya.com
    description: Production
  - url: http://localhost:8080
    description: Development
security: []
tags:
  - name: Identity
  - name: Agents
  - name: Projects
  - name: Pages
  - name: Knowledge
  - name: Assets
  - name: Brand
  - name: Usage
  - name: Chat
paths:
  /v1/agents/{agentId}/query:
    post:
      tags:
        - Agents
      summary: Probe an agent’s retrieval
      description: >-
        Runs the SAME hybrid retrieval a real conversation runs (the
        deterministic topic map plus the vector search, fused) and returns the
        passages the agent would have had, WITHOUT calling the model. Empty
        results mean the agent cannot answer that question yet.
      operationId: PublicAgentsController_query_v1
      parameters:
        - name: agentId
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrievalQueryDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievalResultDto'
        '404':
          description: No such agent in this workspace
      security:
        - api-key: []
components:
  schemas:
    RetrievalQueryDto:
      type: object
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 500
          description: The question, phrased the way a visitor would ask it.
        topics:
          maxItems: 12
          description: >-
            Topics the classifier would have picked. Empty tests the vector half
            alone.
          type: array
          items:
            type: array
        locale:
          type: string
          enum:
            - es
            - en
        limit:
          type: number
          minimum: 1
          maximum: 20
          description: How many passages to return.
      required:
        - query
    RetrievalResultDto:
      type: object
      properties:
        passages:
          type: array
          items:
            $ref: '#/components/schemas/RetrievedPassageDto'
        strategies:
          $ref: '#/components/schemas/RetrievalStrategiesDto'
      required:
        - passages
        - strategies
    RetrievedPassageDto:
      type: object
      properties:
        chunkId:
          type: string
        sourceId:
          type: string
        sourceKind:
          type: string
          enum:
            - upload
            - url
            - claim
        docTitle:
          type: string
        sectionPath:
          type: array
          items:
            type: string
        text:
          type: string
        lang:
          type: string
          enum:
            - es
            - en
        topics:
          type: array
          items:
            type: string
        page:
          type: number
        sourceUrl:
          type: string
        score:
          type: number
          description: Only on passages the vector half found.
      required:
        - chunkId
        - sourceId
        - sourceKind
        - docTitle
        - sectionPath
        - text
        - lang
        - topics
    RetrievalStrategiesDto:
      type: object
      properties:
        topics:
          type: number
          description: Passages the topic map contributed.
        vector:
          type: number
          description: Passages the vector search contributed.
      required:
        - topics
        - vector
  securitySchemes:
    api-key:
      scheme: bearer
      bearerFormat: opaque
      type: http
      description: >-
        A workspace API key: wdy_live_… / wdy_test_…. Created at POST
        /workspaces/{tenantId}/keys and shown exactly once.

````