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

# Q&A

> Responde preguntas usando el conocimiento del agente (Knowledge Base)

Este endpoint devuelve respuestas basadas en la Knowledge Base asociada al `chatbotId`.

* Autenticación: header `X-API-Key` (por workspace). Ver API reference → Keys.
* Requiere: `chatbotId` y `query`.

## Ejemplo de solicitud

```json theme={null}
{
  "query": "cómo puedo evaluar",
  "chatbotId": "<chatbot-id>"
}
```

## Comportamiento

* Busca pasajes/documentos relevantes y genera una respuesta.
* Si la confianza es baja o no hay resultados, devuelve una respuesta genérica y/o error 404 según configuración.
* Opcional: control de `topK` para ajustar el número de pasajes considerados.

## Respuesta

* `answer`: texto generado.
* `citations[]`: referencias a documentos usados (docId, título, url, snippet, score).

Recomendado: validar la respuesta y aplicar umbrales de confianza en producción (ver “Fiabilidad”).


## OpenAPI

````yaml POST /webhook/f71de932-772a-43d6-a7e9-e135c0b03eaa
openapi: 3.1.0
info:
  title: Agents Studio API
  description: >-
    Referencia mínima del endpoint de chat webhook utilizado por el widget y las
    integraciones de Agents Studio.
  version: 1.0.0
servers: []
security:
  - ApiKeyAuth: []
paths:
  /webhook/f71de932-772a-43d6-a7e9-e135c0b03eaa:
    post:
      summary: Responder preguntas con base en el conocimiento del agente
      description: >-
        Devuelve una respuesta basada en la Knowledge Base vinculada al
        `chatbotId` proporcionado.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeQueryRequest'
            examples:
              minimo:
                summary: Consulta mínima
                value:
                  query: cómo puedo evaluar
                  chatbotId: <chatbot-id>
      responses:
        '200':
          description: Respuesta encontrada en la Knowledge Base
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeResponse'
              examples:
                ok:
                  summary: Respuesta con citas
                  value:
                    answer: >-
                      Para evaluar, dirígete a la sección Evaluaciones y
                      selecciona el modelo y conjunto de pruebas.
                    citations:
                      - docId: kb_01HXY...
                        title: Guía de Evaluaciones
                        url: https://example.com/docs/evaluaciones
                        snippet: Ve a Evaluaciones > Nueva evaluación...
                        score: 0.86
                sinResultados:
                  summary: No hay coincidencias suficientes
                  value:
                    answer: >-
                      No encontré información suficiente en el conocimiento para
                      responder con precisión.
                    citations: []
        '400':
          description: Entrada inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Sin resultados relevantes en la Knowledge Base
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Límite de peticiones excedido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Error interno
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    KnowledgeQueryRequest:
      type: object
      required:
        - query
        - chatbotId
      properties:
        query:
          type: string
          description: Pregunta del usuario a responder con el conocimiento.
        chatbotId:
          type: string
          description: ID del chatbot cuyo conocimiento se consultará.
        topK:
          type: integer
          minimum: 1
          maximum: 20
          default: 5
          description: Número de pasajes/documentos a considerar (opcional).
    KnowledgeResponse:
      type: object
      required:
        - answer
      properties:
        answer:
          type: string
          description: Respuesta generada a partir del conocimiento.
        citations:
          type: array
          description: Referencias a los documentos que sustentan la respuesta (si aplica).
          items:
            $ref: '#/components/schemas/Citation'
    Error:
      type: object
      properties:
        code:
          type: string
          description: >-
            Código de error legible por máquina, p. ej., BOT_NOT_AVAILABLE,
            INVALID_INPUT.
        message:
          type: string
          description: Descripción del error.
    Citation:
      type: object
      required:
        - docId
      properties:
        docId:
          type: string
          description: Identificador del documento o fragmento.
        title:
          type: string
          description: Título del documento (si aplica).
        url:
          type: string
          description: URL pública o interna (si aplica).
        snippet:
          type: string
          description: Fragmento relevante del documento.
        score:
          type: number
          format: float
          description: Puntaje de relevancia (0-1).
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Incluye tu API Key en el header X-API-Key. Compatible con n8n (API Key
        simple).

````