La **API pública** de **Aymar Agents** es una superficie REST curada — leads, contactos, conversaciones,
citas y tickets de tu cuenta — pensada para que integres tu propio código, tu CRM o tu automatización con tu
cuenta, sin pasar por la interfaz web. No es un espejo de todo lo que hace la Plataforma: solo existen rutas
para estos 5 recursos, sea cual sea el permiso de tu clave.

Disponible en los planes **Pro** y **Enterprise**. Con el plan Starter, cualquier llamada devuelve
`403 PLAN_NOT_ELIGIBLE` aunque la clave y el permiso sean correctos — ver [Planes y límites](/api/plans-and-limits/).

## 1. Crea tu clave

Las claves de API se crean y gestionan desde **Perfil → Mis claves de API** (o **Ajustes → Claves de API**
para una clave de empresa) — el procedimiento completo, con capturas, está en la guía
**[Claves de API](/guides/claves-api/)**. Al crearla:

- En **«Qué puede hacer esta clave»**, pulsa **«Personalizar»** y marca solo los recursos que tu integración
  necesita — ver el listado completo en [Autenticación](/api/authentication/). Una clave sin el permiso de un
  recurso recibe `403 PERMISSION_DENIED` al llamar a sus rutas, aunque el resto de la clave funcione.
- La clave completa se muestra **una sola vez**: cópiala a un gestor de secretos antes de cerrar el diálogo.

## 2. Comprueba tu clave

`GET /me` no exige ningún permiso propio — solo una clave válida de un tenant con plan elegible — así que es
la forma más rápida de confirmar que todo está en orden:

```bash
curl https://api.aymaragents.com/public/v1/me \
  -H "X-API-Key: aa_TU_CLAVE_COMPLETA"
```

```json
{
  "tenantId": "b3f5b6b0-...",
  "keyPrefix": "aa_1b2e1ebd",
  "scopes": ["tenant:leads.read", "tenant:leads.manage"],
  "plan": "pro",
  "rateLimit": { "perMinute": 180, "perDay": 50000 }
}
```

Si `scopes` no incluye lo que esperabas, revisa el recorte «Personalizar» de tu clave (apartado 7 de la guía
de claves) — el recorte queda sellado al crearla, no se actualiza solo.

## 3. Haz tu primera llamada de negocio

Con una clave que tenga `tenant:leads.read`, lista los leads más recientes:

```bash
curl "https://api.aymaragents.com/public/v1/leads?dateFrom=2026-01-01" \
  -H "X-API-Key: aa_TU_CLAVE_COMPLETA"
```

Cada respuesta de lista usa el mismo formato de paginación que el resto de la API — revisa el campo `meta` de
la respuesta para pedir la página siguiente.

## Antes de automatizar un envío de mensajes

`POST /public/v1/conversations/{id}/messages` y `POST /public/v1/conversations/start` entregan el mensaje al
canal real, pero **no** aparecen al instante en el inbox de la Plataforma ni en el widget del visitante — un
operador humano los ve en el siguiente refresco/reconexión de su pantalla, no en tiempo real. Si tu
integración necesita que un operador reaccione enseguida, avísale por otra vía (tu propio sistema, un
ticket…) además de enviar el mensaje. Detalle completo en la guía de
**[Conversaciones](/api/reference/operations/tags/conversaciones/)** de la referencia.

## Sigue por aquí

- **[Autenticación](/api/authentication/)** — cabecera `X-API-Key`, catálogo completo de permisos.
- **[Planes y límites](/api/plans-and-limits/)** — qué plan necesitas y cuántas peticiones puedes hacer.
- **[Errores](/api/errors/)** — el envelope de error y el catálogo completo de códigos.
- **[Casos de uso](/api/use-cases/)** — 5 integraciones reales con ejemplos de código.
- **Referencia**, en la barra lateral — una página por operación, generada desde la definición
  OpenAPI real de la API.

¿Dudas integrando? Escribe a **soporte@aymaragents.com**.