API y webhooks de RuleAI

Empezar en tres pasos

1. Crea una clave

   En el panel, en API y webhooks, el propietario o el admin de IA crea una clave con los permisos justos y una caducidad de 30, 90 o 365 días. La clave se muestra una sola vez.

2. Comprobar la clave

   Devuelve la empresa, tu rol y los permisos de la clave. Úsalo para saber que todo funciona.

   curl https://demo.ruleaihq.com/api/v1/me \
     -H "Authorization: Bearer rai_live_…"

   const res = await fetch('https://demo.ruleaihq.com/api/v1/me', {
     headers: { Authorization: 'Bearer rai_live_…' },
   });
   const me = await res.json();
   console.log(me);

3. Listar las herramientas de IA

   Lista paginada de 50 en 50. Si hay más, la respuesta trae nextCursor para pedir la siguiente página.

   curl "https://demo.ruleaihq.com/api/v1/tools?limit=50" \
     -H "Authorization: Bearer rai_live_…"

   const res = await fetch('https://demo.ruleaihq.com/api/v1/tools?limit=50', {
     headers: { Authorization: 'Bearer rai_live_…' },
   });
   const { data, nextCursor } = await res.json();

4. Proponer un cambio (borrador)

   Crea un borrador con el permiso «Proponer cambios». Lo revisa y lo publica una persona en Cambios pendientes.

   curl -X POST https://demo.ruleaihq.com/api/v1/drafts \
     -H "Authorization: Bearer rai_live_…" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: factura-2026-10-001" \
     -d '{"entityType":"capability","operation":"create","title":"Registrar el asistente de facturas","data":{"name":"Asistente de facturas","type":"genai","category":"Finanzas"}}'

   const res = await fetch('https://demo.ruleaihq.com/api/v1/drafts', {
     method: 'POST',
     headers: {
       Authorization: 'Bearer rai_live_…',
       'Content-Type': 'application/json',
       'Idempotency-Key': crypto.randomUUID(),
     },
     body: JSON.stringify({
       "entityType": "capability",
       "operation": "create",
       "title": "Registrar el asistente de facturas",
       "data": {
         "name": "Asistente de facturas",
         "type": "genai",
         "category": "Finanzas"
       }
     }),
   });
   const { draft, message } = await res.json(); // estado «pending»

Autenticación

Envía la clave en la cabecera Authorization: Bearer rai_live_…. Las claves de la demo empiezan por rai_test_ y solo funcionan en la demo. Guárdalas como cualquier secreto: nunca en el código ni en el navegador.

Una clave actúa como la persona que la creó, con su rol de hoy y limitada por sus permisos. Si esa persona pierde acceso, la clave también. Las normas del panel siguen valiendo: la privacidad de los datos, la revisión de borradores y la aprobación humana.

• readLeerConsultar herramientas, personas, normas, casos y cambios, con la misma privacidad que el panel.
• drafts:writeProponer cambiosCrear y revisar borradores, preparar paquetes, registrar incidencias y casos. Nunca publica.
• imports:writeImportar datosSubir análisis de uso agregados (se registran al momento, sin datos individuales) y gastos, que llegan como borradores.
• webhooks:writeGestionar webhooksCrear, probar y borrar avisos a tus sistemas.

Errores

Los errores tienen siempre la misma forma, con un código estable y un mensaje en español. Cita el requestId si nos escribes; también va en la cabecera RuleAI-Request-Id.

{
  "error": {
    "code": "FORBIDDEN_SCOPE",
    "message": "Esta clave no tiene el permiso «Proponer cambios».",
    "requestId": "req_…",
    "docs": "https://demo.ruleaihq.com/desarrolladores#errores"
  }
}

• 400
  VALIDATION_ERROR

  El cuerpo o los parámetros no son válidos. El mensaje dice qué campo falla.

• 401
  UNAUTHENTICATED, INVALID_API_KEY, API_KEY_EXPIRED, API_KEY_REVOKED

  Falta la clave, no existe, ha caducado o se ha revocado.

• 403
  FORBIDDEN_SCOPE, FORBIDDEN_ROLE, HUMAN_APPROVAL_REQUIRED

  La clave no tiene ese permiso, tu rol no lo permite o hace falta que una persona lo confirme en el panel.

• 404
  NOT_FOUND

  El recurso no existe o no es visible para ti.

• 409
  Conflictos del dominio

  Alguien cambió el mismo elemento antes; vuelve a leerlo y repite.

• 413 · 415
  —

  Cuerpo demasiado grande o tipo de contenido distinto de application/json.

• 422
  IDEMPOTENCY_MISMATCH

  Reutilizaste una Idempotency-Key con un cuerpo distinto.

• 429
  RATE_LIMITED

  Demasiadas peticiones. Espera a RateLimit-Reset.

• 503
  CONFIGURATION_REQUIRED, SERVICE_UNAVAILABLE

  Falta configuración del servicio o no está disponible. Reintenta más tarde.

Límites, idempotencia y paginación

Todas las respuestas llevan RuleAI-Version: 2026-10-16 y no se guardan en caché.

Referencia

Cada operación con su permiso y un ejemplo. La especificación completa está en /api/v1/openapi.json (OpenAPI 3.1), lista para Postman, Insomnia o tu generador de clientes.

{
  "key": {
    "id": "k3x9…",
    "name": "Integración RR. HH.",
    "scopes": [
      "read"
    ],
    "status": "active"
  },
  "workspace": {
    "id": "nexo",
    "name": "Empresa de ejemplo"
  },
  "role": "admin",
  "scopes": [
    "read"
  ],
  "mode": "demo"
}

{
  "data": [
    {
      "id": "departments-1"
    }
  ],
  "nextCursor": null
}

{
  "data": [
    {
      "id": "people-1"
    }
  ],
  "nextCursor": null
}

{
  "data": [
    {
      "id": "tools-1"
    }
  ],
  "nextCursor": null
}

{
  "name": "Transcripción de llamadas",
  "description": "Transcribir llamadas de soporte.",
  "departmentId": "nexo-ops",
  "type": "genai"
}

{
  "data": [
    {
      "id": "policies-1"
    }
  ],
  "nextCursor": null
}

{
  "dataClass": "internal",
  "tool": "Asistente de redacción"
}

{
  "allowed": false,
  "policyIds": [],
  "reason": "No existe una autorización publicada para esta combinación."
}

{
  "data": [
    {
      "id": "use-cases-1"
    }
  ],
  "nextCursor": null
}

{
  "data": [
    {
      "id": "shared-cases-1"
    }
  ],
  "nextCursor": null
}

{
  "title": "Resumen de reuniones",
  "description": "Resumir actas semanales con revisión humana.",
  "departmentId": "nexo-ops",
  "unusual": false
}

{
  "data": [
    {
      "id": "drafts-1"
    }
  ],
  "nextCursor": null
}

{
  "entityType": "capability",
  "operation": "create",
  "title": "Añadir asistente de redacción",
  "data": {
    "name": "Asistente de redacción",
    "description": "Borradores de correos internos.",
    "type": "genai",
    "departmentIds": [
      "nexo-ops"
    ]
  }
}

{
  "message": "Borrador creado. Requiere revisión y aprobación en el panel.",
  "revision": 42,
  "data": {
    "draftId": "6f1c…"
  },
  "draft": {
    "id": "6f1c…",
    "status": "pending"
  }
}

{
  "data": {
    "description": "Texto corregido."
  }
}

{
  "verdict": "safe",
  "reasoning": "Fuentes y alcance comprobados."
}

{
  "data": [
    {
      "id": "bundles-1"
    }
  ],
  "nextCursor": null
}

{
  "draftIds": [
    "6f1c…"
  ],
  "title": "Altas de octubre"
}

{
  "error": {
    "code": "HUMAN_APPROVAL_REQUIRED",
    "message": "Publicar cambios requiere que una persona lo confirme en el panel.",
    "requestId": "req_…",
    "docs": "…/desarrolladores#errores",
    "approveUrl": "…/app/aprobaciones?bundle=…"
  }
}

{
  "data": [
    {
      "id": "incidents-1"
    }
  ],
  "nextCursor": null
}

{
  "title": "Datos de cliente en un chat externo",
  "description": "Se pegó un listado en una herramienta no autorizada.",
  "severity": "high",
  "departmentId": "nexo-ops"
}

{
  "data": [
    {
      "id": "processes-1"
    }
  ],
  "nextCursor": null
}

{
  "data": [
    {
      "id": "glossary-1"
    }
  ],
  "nextCursor": null
}

{
  "data": [
    {
      "id": "next-steps-1"
    }
  ],
  "nextCursor": null
}

{
  "mode": "preview",
  "csv": "vendor,tool,amount,currency,period\nProveedor,Herramienta,20.00,EUR,2026-09"
}

{
  "url": "https://example.test/ruleai",
  "events": [
    "draft.created",
    "bundle.approved"
  ]
}

Webhooks

RuleAI envía un POST con JSON a tu dirección cuando pasa algo. Los avisos son ligeros: identificadores, tipo y hora, nunca nombres, correos ni textos. Para el detalle, pide el recurso a la API. Si tu sistema no puede recibir avisos, consulta GET /api/v1/events (últimos 30 días).

• draft.createdNuevo borrador
• draft.reviewedBorrador revisado
• draft.rejectedBorrador rechazado
• bundle.preparedPaquete listo para aprobar
• bundle.approvedCambios publicados
• bundle.revertedCambios deshechos
• incident.createdNueva incidencia
• incident.resolvedIncidencia resuelta
• import.completedDatos de uso importados
• shared_case.createdCaso compartido

{
  "id": "evt_…",
  "type": "bundle.prepared",
  "workspaceId": "ws_…",
  "createdAt": "2026-10-16T09:30:00.000Z",
  "data": {
    "object": "bundle",
    "id": "bun_…",
    "status": "ready"
  }
}

Firma

Cada aviso lleva RuleAI-Signature: t=<segundos>,v1=<hmac>, donde v1 es el HMAC-SHA256 en hexadecimal de `${t}.${cuerpo}` con tu secreto whsec_…. También van RuleAI-Event-Id, RuleAI-Event-Type y User-Agent: RuleAI-Webhooks/1. Rechaza los avisos con más de 5 minutos y usa el id del evento para no procesarlo dos veces.

import crypto from 'node:crypto';

// Usa el cuerpo tal cual llega (Buffer o texto), antes de convertirlo a JSON.
export function verifyRuleAiSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // más de 5 minutos
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  const given = Buffer.from(parts.v1 ?? '', 'hex');
  const wanted = Buffer.from(expected, 'hex');
  return given.length === wanted.length && crypto.timingSafeEqual(given, wanted);
}

// app.post('/hook', express.raw({ type: 'application/json' }), (req, res) => {
//   if (!verifyRuleAiSignature(req.body, req.get('RuleAI-Signature'), process.env.RULEAI_WEBHOOK_SECRET))
//     return res.status(400).end();
//   const event = JSON.parse(req.body);   // { id, type, workspaceId, createdAt, data }
//   res.status(200).end();                // responde rápido; procesa después
// });

Reintentos

Responde con un 2xx en menos de 10 segundos. Si no, lo intentamos hasta 6 veces en total, esperando 1 min, 5 min, 30 min, 2 h, 12 h entre intentos. Desde el panel puedes enviar una prueba y ver las entregas recientes.