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

# Agregar documentos

> Agregar uno o múltiples documentos de texto a tu datastore.

## Endpoint

```
POST /api/external/datastores/upsert/{datastoreId}
```

## Path Parameters

<ParamField path="datastoreId" type="string" required>
  ID del datastore donde agregar los documentos.
</ParamField>

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token con tu API key de organización.
</ParamField>

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

## Request Body

<ParamField body="documents" type="array" required>
  Array de documentos a agregar.

  <Expandable title="Propiedades de cada documento">
    <ParamField body="documents[].name" type="string">
      Nombre identificador del documento.
    </ParamField>

    <ParamField body="documents[].text" type="string" required>
      Contenido del documento. Se procesa y divide en chunks automáticamente.
    </ParamField>

    <ParamField body="documents[].metadata" type="object">
      Metadata adicional para filtros y organización.

      <Expandable title="Ejemplo de metadata">
        <ParamField body="documents[].metadata.categoria" type="string">
          Categoría del documento
        </ParamField>

        <ParamField body="documents[].metadata.version" type="string">
          Versión del documento
        </ParamField>

        <ParamField body="documents[].metadata.autor" type="string">
          Autor del documento
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://app.horneross.com/api/external/datastores/upsert/ds_abc123 \
    -H "Authorization: Bearer sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "documents": [
        {
          "name": "Política de envíos",
          "text": "Realizamos envíos a todo el país. El costo depende de la zona y el peso del paquete. Envíos gratis en compras mayores a $50.000.",
          "metadata": {
            "categoria": "envios",
            "version": "2024-01"
          }
        },
        {
          "name": "Política de devoluciones",
          "text": "Podés devolver tu producto dentro de los 30 días desde la compra.",
          "metadata": {
            "categoria": "devoluciones"
          }
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://app.horneross.com/api/external/datastores/upsert/ds_abc123',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_live_xxx',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        documents: [
          {
            name: 'Producto: Laptop Pro',
            text: 'La Laptop Pro cuenta con procesador Intel i7, 16GB RAM...',
            metadata: { tipo: 'producto', sku: 'LP-2024' },
          },
        ],
      }),
    }
  );

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

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

  response = requests.post(
      'https://app.horneross.com/api/external/datastores/upsert/ds_abc123',
      headers={
          'Authorization': 'Bearer sk_live_xxx',
          'Content-Type': 'application/json',
      },
      json={
          'documents': [
              {
                  'name': 'FAQ General',
                  'text': 'Preguntas frecuentes sobre nuestros servicios...',
                  'metadata': {'categoria': 'faq'}
              }
          ]
      }
  )

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

## Response

<ResponseField name="ids" type="string[]" required>
  Array de IDs de los datasources creados
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "ids": ["datasource_123", "datasource_456"]
  }
  ```

  ```json 400 - Bad Request theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "message": "El campo 'text' es requerido en cada documento"
    }
  }
  ```
</ResponseExample>