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

# Buscar en datastore

> Realizar búsquedas semánticas en tu base de conocimiento.

## Endpoint

```
POST /api/datastores/{datastoreId}/query
```

## Path Parameters

<ParamField path="datastoreId" type="string" required>
  ID único del datastore donde realizar la búsqueda.
</ParamField>

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token con tu API key o API key del datastore.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Siempre `application/json`
</ParamField>

## Request Body

<ParamField body="query" type="string" required>
  Texto de búsqueda. El sistema encuentra documentos semánticamente similares.
</ParamField>

<ParamField body="topK" type="number" default="5">
  Cantidad de resultados a retornar. Máximo 20.
</ParamField>

<ParamField body="filters" type="object">
  Filtros de metadata para refinar la búsqueda.

  <Expandable title="Propiedades de filters">
    <ParamField body="filters.custom_id" type="string">
      Filtrar por ID personalizado
    </ParamField>

    <ParamField body="filters.datasource_ids" type="string[]">
      Filtrar por IDs de datasources específicos
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://app.horneross.com/api/datastores/ds_abc123/query \
    -H "Authorization: Bearer sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "política de devoluciones",
      "topK": 3
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.horneross.com/api/datastores/ds_abc123/query',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_live_xxx',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        query: 'política de devoluciones',
        topK: 3,
      }),
    }
  );

  const results = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://app.horneross.com/api/datastores/ds_abc123/query',
      headers={
          'Authorization': 'Bearer sk_live_xxx',
          'Content-Type': 'application/json',
      },
      json={
          'query': 'política de devoluciones',
          'topK': 3
      }
  )

  results = response.json()
  ```
</RequestExample>

## Response

<ResponseField name="results" type="array" required>
  Array de documentos encontrados ordenados por relevancia.

  <Expandable title="Propiedades de cada resultado">
    <ResponseField name="results[].text" type="string" required>
      Contenido del fragmento de texto encontrado
    </ResponseField>

    <ResponseField name="results[].score" type="number" required>
      Score de similitud (0-1). Mayor es más relevante.
    </ResponseField>

    <ResponseField name="results[].source" type="string">
      URL o nombre de la fuente original
    </ResponseField>

    <ResponseField name="results[].datasource_name" type="string">
      Nombre del datasource de origen
    </ResponseField>

    <ResponseField name="results[].datasource_id" type="string">
      ID del datasource de origen
    </ResponseField>

    <ResponseField name="results[].custom_id" type="string">
      ID personalizado si fue asignado
    </ResponseField>

    <ResponseField name="results[].offset" type="number">
      Offset del chunk dentro del documento
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null}
  [
    {
      "text": "Podés devolver tu producto dentro de los 30 días desde la compra. El producto debe estar sin uso y en su empaque original.",
      "score": 0.95,
      "source": "https://ejemplo.com/politicas",
      "datasource_name": "Políticas de la empresa",
      "datasource_id": "datasource_xyz",
      "custom_id": "politica_devoluciones",
      "offset": 0
    }
  ]
  ```

  ```json 404 - Not Found theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "message": "Datastore no encontrado"
    }
  }
  ```
</ResponseExample>