/api/v1/* — referencia pública, sin humo

Autenticación

Todas las llamadas a /api/v1/* van con un Bearer token (API key del workspace). Minteá tokens en /settings/api-keys.

• Header aceptado: Authorization: Bearer <key> o X-Api-Key: <key> (alias legacy).
• Cada key tiene un tier técnico (1× / 2× / 4×) que determina rate limits y cuota de ingest. Ver §Rate limits.
• Scopes son capability-based: cada endpoint pide un scope específico de la lista en §Scopes. Keys sin ese scope reciben 403.
• Rotación: POST /settings/api-keys/:id/rotate (UI) o vía CLI. Grace window 24 h — la key vieja sigue válida.

Rate limits por tier

El tier de una key define dos cosas: rate por minuto y cuota mensual de ingest. Cada response incluye headers X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. En 429 llega Retry-After.

Los números técnicos pueden ajustarse con acuerdo SLA en Institutional. Para upgrades temporarios, abrí ticket en enterprise@fuvihub.com.

Scopes (23 routed)

Al mintear una key, elegí solo los scopes que vayas a usar. El principio es least-privilege: keys de ingest no deberían poder leer reports, y viceversa.

Endpoints

Grupos por dominio. Click en el path para copiar. Todas las respuestas son JSON con envelope { data, meta, error }.

Webhooks salientes

FUVIHUB emite eventos por HTTP POST firmados con HMAC-SHA256. El receptor verifica sin confiar en la red.

Headers entregados

• X-Veil-Signature: `sha256=<hex>`. HMAC sobre el raw body con el secret de la subscripción.
• X-Veil-Event-Id: identificador único; usalo para deduplicar.
• X-Veil-Event-Type: ej. insight.created, alert.fired, brief.published.
• X-Veil-Delivery-Attempt: número de intento (1..N). Reintentos con backoff exponencial, máx 5.

Verificación (Node.js)

Delivery guarantees

• At-least-once: duplicá por X-Veil-Event-Id.
• Timeout: 8 s (configurable vía PLATFORM_WEBHOOK_TIMEOUT_MS).
• Reintentos: hasta 5 con backoff exponencial. Después queda dropped y es replay-ableable via POST /api/v1/webhook-deliveries/:id/replay.
• Rotación de secret: grace window de 24 h. Durante ese tiempo ambos secrets son aceptados por el verificador.

Errores y códigos

Toda respuesta de error trae envelope { error: { code, message, details?, correlationId } }. El code es estable; la mensaje puede cambiar.

SDK y snippets

Hoy no publicamos un SDK como paquete npm — la API es lo suficientemente compacta para consumirla con fetch nativo. Si necesitás un SDK tipado, compartimos un cliente TypeScript interno bajo acuerdo en Strategic+ (pedílo a developers@fuvihub.com).

await fetch("https://app.fuvihub.com/api/v1/feedback", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [{
      externalId: "crm-123",
      source: "hubspot",
      content: "...",
      createdAt: new Date().toISOString(),
    }],
  }),
});

const res = await fetch(
  "https://app.fuvihub.com/api/v1/intelligence/briefs?range=7d",
  { headers: { Authorization: "Bearer " + API_KEY } },
);
const { data } = await res.json();
for (const brief of data) {
  console.log(brief.title, brief.confidence);
}