Referencia API

La API pública (/public/v1) es una superficie REST curada de 5 recursos — leads, contactos, conversaciones, citas y tickets — autenticada por clave de API, disponible en los planes Pro y Enterprise.

Empezar con la APICrea tu clave y haz tu primera llamada en menos de 10 minutos.

AutenticaciónCabecera X-API-Key, scopes por recurso y por acción.

Tu primera petición

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 comprobar que tu clave funciona:

curl

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

Python

import requests

res = requests.get(
    "https://api.aymaragents.com/public/v1/me",
    headers={"X-API-Key": "aa_TU_CLAVE_COMPLETA"},
)
res.raise_for_status()
print(res.json())

JavaScript

const res = await fetch("https://api.aymaragents.com/public/v1/me", {
  headers: { "X-API-Key": "aa_TU_CLAVE_COMPLETA" },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());

Guías

Planes y límitesQué plan necesitas y cuántas peticiones puedes hacer.

ErroresFormato de error y códigos que puede devolver la API.

VersionadoCómo evoluciona /public/v1 sin romper tu integración.

Casos de uso de la APIEscenarios reales de integración.

Referencia generada

EndpointsCada operación de /public/v1, generada de la misma definición OpenAPI que usa el servidor MCP.

Herramientas relacionadas

Servidor MCPConecta tu asistente de IA a la misma API.

llms.txtÍndice de todo el portal en texto plano.

Preguntas frecuentes

¿Qué plan necesito para usar la API pública?

Pro o Enterprise. Con el plan Starter, cualquier llamada a /public/v1/* responde 403 PLAN_NOT_ELIGIBLE, aunque la clave exista y tenga el scope correcto. Ver Planes y límites.

¿Qué pasa si mi clave no tiene el scope exacto que pide un endpoint?

Recibes 403 PERMISSION_DENIED, aunque tenga el resto de sus permisos. Cada recurso tiene dos scopes independientes — lectura y gestión. Ver Autenticación.

¿Cómo roto una clave sin cortar mi integración?

Hoy no hay un endpoint de rotación atómica: crea una clave nueva con los mismos scopes, actualiza el secreto en tu integración y luego revoca la antigua — hay una ventana breve con ambas activas.

¿Qué devuelve la API si pido un recurso de otro tenant?

404, exactamente igual que si el recurso no existiera — nunca 403, que confirmaría que el dato existe en otra cuenta.

¿Cuántas peticiones puedo hacer por minuto?

180/minuto y 50.000/día en Pro; 600/minuto y 200.000/día en Enterprise. El cupo se contabiliza por clave, no por IP. Ver Planes y límites.

¿Puedo borrar un lead, un contacto o cualquier otro recurso por la API?

No — /public/v1 no tiene ningún endpoint DELETE. Ver Casos de uso de la API.

¿Qué pasa si envío un mensaje de WhatsApp fuera de la ventana de 24 horas?

Recibes 409 WHATSAPP_SESSION_WINDOW_CLOSED — usa POST /conversations/start con una plantilla aprobada en su lugar. Ver Errores.

Siguiente

Servidor MCPConecta Claude, Cursor u otro asistente de IA a tu cuenta.