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

# Empezar con la API

> Todo lo que necesitás para integrar Horneross programáticamente en tus sistemas.

La API de Horneross te permite integrar agentes de IA en cualquier aplicación, automatizar flujos de trabajo y gestionar conversaciones de manera programática.

## Capacidades

<CardGroup cols={2}>
  <Card title="Chat con Agentes" icon="message-bot">
    Envía mensajes y recibí respuestas de tus agentes desde cualquier sistema
  </Card>

  <Card title="Gestión de Conocimiento" icon="database">
    Agregá, actualizá y consultá documentos en tus datastores
  </Card>

  <Card title="Conversaciones" icon="messages">
    Accedé al historial completo y gestioná el estado de conversaciones
  </Card>

  <Card title="Webhooks" icon="webhook">
    Recibí eventos en tiempo real cuando algo importante sucede
  </Card>
</CardGroup>

## Configuración inicial

### 1. Obtener tu API Key

<Steps>
  <Step title="Ingresá al Dashboard">
    Andá a [app.horneross.com](https://app.horneross.com) e iniciá sesión
  </Step>

  <Step title="Accedé a Settings">
    Navegá a **Settings** → **API Keys** en el menú lateral
  </Step>

  <Step title="Creá una nueva key">
    Click en **"Nueva API Key"** y asignale un nombre descriptivo
  </Step>

  <Step title="Guardá la key">
    Copiá y guardá la key en un lugar seguro. Solo se muestra una vez.
  </Step>
</Steps>

<Warning>
  **Seguridad**: Nunca expongas tu API key en código del lado del cliente (frontend).
  Usala únicamente en tu backend.
</Warning>

### 2. Obtener el Agent ID

El `agentId` lo encontrás de dos formas:

1. **En la URL**: `app.horneross.com/agents/[AGENT_ID]/...`
2. **En el Dashboard**: Andá a tu agente → **Configuración** → **General** → **Agent ID**

### 3. Tu primera request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://app.horneross.com/api/v2/agent/TU_AGENT_ID/chat \
      -H "Authorization: Bearer TU_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "Hola, necesito ayuda con mi pedido",
        "conversationId": "conv_nuevo"
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch(
      'https://app.horneross.com/api/v2/agent/TU_AGENT_ID/chat',
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer TU_API_KEY',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          query: 'Hola, necesito ayuda con mi pedido',
          conversationId: 'conv_nuevo'
        }),
      }
    );

    const data = await response.json();
    console.log(data.answer);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        'https://app.horneross.com/api/v2/agent/TU_AGENT_ID/chat',
        headers={
            'Authorization': 'Bearer TU_API_KEY',
            'Content-Type': 'application/json',
        },
        json={
            'query': 'Hola, necesito ayuda con mi pedido',
            'conversationId': 'conv_nuevo'
        }
    )

    data = response.json()
    print(data['answer'])
    ```
  </Tab>
</Tabs>

### 4. Respuesta

```json theme={null}
{
  "answer": "¡Hola! Con gusto te ayudo con tu pedido. ¿Podrías darme el número de orden?",
  "conversationId": "conv_nuevo",
  "messageId": "msg_abc123xyz",
  "sources": [
    {
      "source": "Políticas de envío",
      "score": 0.92
    }
  ],
  "usage": {
    "promptTokens": 150,
    "completionTokens": 45
  }
}
```

## Conceptos clave

| Concepto         | Descripción                                                 |
| ---------------- | ----------------------------------------------------------- |
| `agentId`        | Identificador único de cada agente                          |
| `conversationId` | Agrupa mensajes de una misma conversación                   |
| `visitorId`      | Identifica a un usuario único (para agrupar conversaciones) |
| `contact`        | Datos del contacto (email, nombre, teléfono)                |
| `datastoreId`    | Identificador de una base de conocimiento                   |

## Mantener contexto en conversaciones

Para que el agente recuerde mensajes anteriores, usá el mismo `conversationId`:

```javascript theme={null}
// Primera pregunta
const primera = await chat({
  query: "¿Cuáles son los horarios de atención?",
  conversationId: "conv_usuario_123"
});
// El agente responde con los horarios

// Segunda pregunta (el agente recuerda el contexto)
const segunda = await chat({
  query: "¿Y los sábados?",
  conversationId: "conv_usuario_123"
});
// El agente sabe que estás preguntando por horarios del sábado
```

## Identificar usuarios

Usá `visitorId` para agrupar todas las conversaciones de un mismo usuario:

```javascript theme={null}
const response = await chat({
  query: "Quiero información sobre precios",
  visitorId: "usuario_456",
  contact: {
    email: "cliente@ejemplo.com",
    firstName: "María",
    lastName: "García",
    phoneNumber: "+5491123456789"
  }
});
```

Esto crea o actualiza el contacto en tu CRM interno de Horneross.

## Base URL

Todas las requests van a:

```
https://app.horneross.com/api
```

## Autenticación

Incluí tu API key en el header `Authorization`:

```
Authorization: Bearer TU_API_KEY
```

## Rate Limits

| Plan       | Requests/min | Requests/día |
| ---------- | ------------ | ------------ |
| Free       | 10           | 1,000        |
| Starter    | 60           | 10,000       |
| Pro        | 300          | 100,000      |
| Enterprise | Custom       | Custom       |

<Info>
  Si necesitás más capacidad, contactanos para un plan Enterprise.
</Info>

## Códigos de error comunes

| Código | Problema                       | Solución                                       |
| ------ | ------------------------------ | ---------------------------------------------- |
| `401`  | API key inválida o expirada    | Verificá que la key sea correcta y esté activa |
| `403`  | Sin permisos para este recurso | Verificá que tu plan tenga acceso al endpoint  |
| `404`  | Recurso no encontrado          | Verificá el `agentId`, `datastoreId`, etc.     |
| `429`  | Rate limit excedido            | Esperá antes de reintentar o upgradea tu plan  |
| `500`  | Error interno del servidor     | Reintentá en unos segundos                     |

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Chat API" icon="message-bot" href="/developers/api/chat">
    Endpoint principal para conversar con agentes
  </Card>

  <Card title="Datastores API" icon="database" href="/developers/api/datastores">
    Gestionar bases de conocimiento
  </Card>

  <Card title="MCP Integration" icon="plug" href="/developers/mcp/index">
    Conectá herramientas externas via MCP
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developers/webhooks">
    Recibí eventos en tiempo real
  </Card>
</CardGroup>