# Referencia de la API

API REST + WebSocket para agentes, chats, conocimiento, herramientas, teléfonos y webhooks

> Full REST + WebSocket API reference: https://api.happ.tools/reference

Happ ofrece una API REST + WebSocket para gestionar agentes, enviar mensajes, controlar el modo IA e integrar Happ en tus flujos de trabajo. La referencia completa y que se puede probar está en Scalar: es la fuente de verdad de cada endpoint, esquema y ejemplo.

**[api.happ.tools/reference](https://api.happ.tools/reference)**

## Grupos de recursos [#resource-groups]

La referencia pública cubre estos grupos:

* **Auth**: iniciar sesión, renovar un token
* **Companies**: espacios de trabajo, miembros, invitaciones
* **Access Tokens**: tokens de larga duración para integraciones
* **Assistants**: `GET/POST /api/assistants-new`, `PATCH /api/assistants-new/{id}`
* **Assistant tools**: `/api/assistant-tools-new`
* **Assistant knowledge**: `/api/assistant-knowledge-new`
* **Chats**: listar chats, enviar y listar mensajes, activar o desactivar el control de la IA (`PATCH /api/chats/{id}` `isUnderAiControl`)
* **Calls**: iniciar una llamada saliente: `POST /api/assistants/{id}/originate`

Todo lo demás de la plataforma (teléfonos, integraciones, facturación, analítica) se gestiona desde el panel, no desde la API pública.

## Autenticación [#authentication]

Todas las peticiones requieren un **Access Token** generado en la configuración de la cuenta en [my.happ.tools](https://my.happ.tools). Envíalo en la cabecera:

```
X-Access-Token: happ_your_token_here
```

URL base (producción): `https://api.happ.tools`.

## WebSocket [#websocket]

Conéctate por Socket.IO a `wss://api.happ.tools` (namespace por defecto, sin sufijo de ruta): autentícate con tu token, pasa `auth: { companyId }` y recibe los eventos `MESSAGE_CREATED`, `CHAT_MODE_CHANGED` y `CHAT_CREATED`. Consulta [Chats > Actualizaciones en tiempo real](/docs/workspace/chats).

## Uso con IA [#use-with-ai]

¿Integras con un asistente de IA (Claude, Cursor, Copilot)? Dale nuestras fuentes legibles por máquina en lugar de copiar y pegar la documentación:

* **Especificación OpenAPI**: `https://api.happ.tools/api/swagger-json` (cada endpoint, esquema y regla de autenticación)
* **Índice de la documentación**: `https://docs.happ.tools/llms.txt`

Prompt inicial:

```text
You are integrating with the Happ Platform API.
Spec: https://api.happ.tools/api/swagger-json
Docs: https://docs.happ.tools/llms.txt
Auth: send the header X-Access-Token: happ_...
Task: <describe what you want to build>
```

## Siguiente [#next]

* [Chats](/docs/workspace/chats): la bandeja de entrada que manejan estos endpoints
* [Webhooks](/docs/integrations/webhooks): envía eventos a tu servidor