Public API reference · v1

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

Esta es la lista real de endpoints, scopes y errores que shippeamos hoy. Si un endpoint está acá, existe en src/app/api/v1/**. Si no aparece, no existe — y no lo vamos a prometer.

Auth Rate limits Scopes Endpoints Errors Webhooks

Autenticación

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

curl -X POST https://app.fuvihub.com/api/v1/feedback \

-H "Authorization: Bearer fb_live_xxxxxxxxxxxx" \

-H "Content-Type: application/json" \

-d '{"items":[{"externalId":"abc-1","source":"typeform","content":"..."}]}'

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.

Tier	Rate (request)	Cuota mensual	Uso típico
Básica (1×)	60 req/min · 1 req/s sostenido	5.000 ingest / mes	Dev / staging / integraciones pequeñas. Incluido en Launch.
Intermedia (2×)	120 req/min · 2 req/s sostenido	25.000 ingest / mes	Integraciones productivas. Incluido en Operator + Strategic.
Avanzada (4×)	240 req/min · 4 req/s sostenido	100.000 ingest / mes	Ingest masivo + webhooks high-freq. Incluido en Strategic + Institutional.

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

Scopes (25 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.

Scope	Etiqueta UI	Descripción
feedback:write	Ingest structured signals	Create signal records via POST /api/v1/feedback (compat endpoint name retained).
feedback:read	Read signal records	List structured signal records via GET /api/v1/feedback.
insights:read	Read insights	List and retrieve generated intelligence insights.
alerts:read	Read alerts	List and retrieve prioritized alerts.
reports:read	Read briefings / digests	List and retrieve strategic briefings (7d / 30d / 90d).
review:write	Process curation queue	Curate the classification and review queue.
schedules:read	Read automation schedules	Read automation schedule configuration.
schedules:write	Manage automation schedules	Create, pause or delete automation schedules.
targets:read	Read delivery endpoints	Read configured delivery endpoints.
targets:write	Manage delivery endpoints	Create, update or disable delivery endpoints.
billing:read	Read plans & usage	Read the workspace's usage snapshot and platform plan limits.
webhooks:read	Read webhook subscriptions	List webhook subscriptions and their recent deliveries.
webhooks:write	Manage webhook subscriptions	Create, rotate, enable/disable, test and replay webhook subscriptions.
audiences:read	Read audiences & segments	List audiences and their criteria for dispatch segmentation.
audiences:write	Manage audiences & segments	Create, update or archive audiences; rotate embed secrets.
embeds:read	Mint signed embed tokens	Mint a short-lived signed token to render a read-only audience snapshot.
packs:read	Discover vertical packs	Enumerate the vertical packs (Voice / Radar / Commerce / Healthcare / Edu / Fintech / Retail / SaaS-SRE) available on this workspace.
intelligence:read	Read intelligence briefs	List and retrieve IntelligenceBrief rollups (Release 4 B).
intelligence:write	Generate & publish intelligence briefs	Generate, draft, publish or archive an IntelligenceBrief.
policies:read	Read the organization governance policy	Read the single-source-of-truth OrganizationPolicy row (Release 4 G).
policies:write	Update the organization governance policy	Update the organization governance policy (API key mint role, embed TTL ceiling, provisioning mode, brief publish role, …).
scim-groups:read	Read SCIM group bindings	Read SCIM group bindings and member counts.
scim-groups:write	Manage SCIM group bindings	Create, update or archive SCIM group bindings (role and pack scoping).
foresight:read	Read Foresight panel runs	Read persisted Foresight panel runs (predictions, deliberation, evidence, top responses).
foresight:write	Run Foresight synthetic-citizen panels (consume credits)	Run a Foresight synthetic-citizen panel — consumes wallet credits and is gated by plan tier.

Endpoints

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

Ingest — escribir señales

Punto de entrada para pipelines externos (CRM, helpdesk, ETL). Idempotente por externalId. Alias de nombre legacy (feedback) preservado.

Verb	Path	Scope	Resumen
POST	/api/v1/feedback	feedback:write	Insertar 1..N señales. Batch up to 500 items/request.Responde 201 (todo OK) o 207 (aceptadas parciales). Rate limit por key: tier 1× = 60/min, 2× = 120/min, 4× = 240/min.
GET	/api/v1/feedback	feedback:read	Listar señales con filtros (source, createdAfter, cursor).

Insights & alertas — lectura de derivados

Rollups determinísticos computados por el motor de classify+insights. Todos los objetos traen confidence + evidence[].

Verb	Path	Scope	Resumen
GET	/api/v1/insights	insights:read	Listar insights con filtros (range, status, cursor).
GET	/api/v1/alerts	alerts:read	Alertas priorizadas (severity ≥ configurada en pack).
GET	/api/v1/scenarios	insights:read	Escenarios de Radar con top opportunities + top risks.

Reports — briefs 7d/30d/90d

Briefings estratégicos generados por Intelligence Layer (determinísticos). Ver también /api/v1/intelligence/briefs.

Verb	Path	Scope	Resumen
GET	/api/v1/reports	reports:read	Listar reports por rango temporal.
GET	/api/v1/reports/:id	reports:read	Recuperar report específico con evidence[].
GET	/api/v1/intelligence/briefs	intelligence:read	Listar briefs v3 del workspace.
GET	/api/v1/intelligence/briefs/:id	intelligence:read	Recuperar brief específico con signalIds citados.
POST	/api/v1/intelligence/briefs	intelligence:write	Generar brief bajo demanda (rango + audiencia opcional).
PATCH	/api/v1/intelligence/briefs/:id	intelligence:write	Publicar / archivar brief.

Review queue — curación

Queue de señales que quedaron en review (confidence < 0.7 o categoría ambigua).

Verb	Path	Scope	Resumen
POST	/api/v1/review	review:write	Decisión (approve / reject / recategorize) sobre items.

Schedules — automatización

Schedules periódicos (digest, scanner, brief). Cada tick genera un JobRun auditado.

Verb	Path	Scope	Resumen
GET	/api/v1/schedules	schedules:read	Listar schedules activos.
POST	/api/v1/schedules	schedules:write	Crear schedule (cron + tipo + params).
GET	/api/v1/schedules/:id	schedules:read	Inspeccionar schedule con últimos JobRuns.
PATCH	/api/v1/schedules/:id	schedules:write	Pausar / reanudar / editar cron.
DELETE	/api/v1/schedules/:id	schedules:write	Eliminar schedule (borra futuros JobRuns, preserva historia).

Delivery targets — canales salientes

Endpoints (email, slack, webhook) donde se despachan briefs y alertas.

Verb	Path	Scope	Resumen
GET	/api/v1/targets	targets:read	Listar delivery targets.
POST	/api/v1/targets	targets:write	Crear target (kind + config cifrada en reposo).
GET	/api/v1/targets/:id	targets:read	Inspeccionar target con últimos eventos de entrega.
PATCH	/api/v1/targets/:id	targets:write	Editar target (rotar secret, cambiar URL, habilitar/deshabilitar).
DELETE	/api/v1/targets/:id	targets:write	Archivar target (no destructivo).

Audiences & embeds — segmentación + signed tokens

Audiencias con criteria + tokens firmados para embeber snapshots read-only en surfaces externas.

Verb	Path	Scope	Resumen
GET	/api/v1/audiences	audiences:read	Listar audiencias del workspace.
POST	/api/v1/audiences	audiences:write	Crear audiencia (criteria + embed settings).
GET	/api/v1/audiences/:id	audiences:read	Detalle de audiencia incluyendo criteria y embed secret status.
PATCH	/api/v1/audiences/:id	audiences:write	Editar criteria, renombrar, archivar.
GET	/api/v1/audiences/preview	audiences:read	Preview del tamaño de una audiencia con criteria provisorios.
POST	/api/v1/audiences/:id/embed-secret	audiences:write	Rotar el secret HMAC del embed (grace window 24 h).
POST	/api/v1/audiences/:id/embed-token	embeds:read	Mint short-lived signed token para el embed.
POST	/api/v1/embeds/events	embeds:read	Registrar evento de uso del embed (para billing / telemetry).

Packs — discovery de verticales

Catalogo de los 8 packs verticales. Read-only.

Verb	Path	Scope	Resumen
GET	/api/v1/packs	packs:read	Enumerar packs (voice/radar/commerce/fintech/healthcare/retail/edu/saas-sre).

Webhooks — subscriptions salientes

Subscripciones HMAC-firmadas a eventos del workspace. Delivery con reintentos + replay.

Verb	Path	Scope	Resumen
GET	/api/v1/webhooks	webhooks:read	Listar subscripciones del workspace.
POST	/api/v1/webhooks	webhooks:write	Crear subscripción (url + eventTypes[]).
GET	/api/v1/webhooks/:id	webhooks:read	Detalle de subscripción con scopes y health.
PATCH	/api/v1/webhooks/:id	webhooks:write	Editar url, event types, enable/disable.
DELETE	/api/v1/webhooks/:id	webhooks:write	Revocar subscripción (preserva historia de deliveries).
POST	/api/v1/webhooks/:id/rotate	webhooks:write	Rotar secret HMAC (grace window 24 h).
POST	/api/v1/webhooks/:id/test	webhooks:write	Disparar evento de prueba (ping).
GET	/api/v1/webhooks/:id/deliveries	webhooks:read	Paginar deliveries recientes con status + response.
POST	/api/v1/webhook-deliveries/:id/replay	webhooks:write	Re-ejecutar una delivery puntual (idempotente).

Governance — policies + SCIM groups

Gestión programática de la policy organizacional y de los bindings SCIM Group ↔ rol/packs.

Verb	Path	Scope	Resumen
GET	/api/v1/policies	policies:read	Leer la policy (single row, versionada).
PATCH	/api/v1/policies	policies:write	Actualizar policy (mint role, embed TTL, provisioning mode...).
GET	/api/v1/scim-groups	scim-groups:read	Listar bindings SCIM Group → rol + packs.
POST	/api/v1/scim-groups	scim-groups:write	Crear binding (groupExternalId → role).

Billing — usage snapshot

Read-only: snapshot de usage y plan del workspace (para dashboards internos).

Verb	Path	Scope	Resumen
GET	/api/v1/usage	billing:read	Usage actual del periodo + límites del plan.

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)

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(body, header, secret) {

const expected = createHmac("sha256", secret).update(body).digest("hex");

const received = header.replace(/^sha256=/, "");

const a = Buffer.from(expected, "hex");

const b = Buffer.from(received, "hex");

return a.length === b.length && timingSafeEqual(a, b);

}

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.

Code	HTTP	Significado
unauthorized	401	Bearer token ausente, inválido o revocado.
forbidden	403	Auth OK pero el scope requerido no está en la key.
not_found	404	Recurso no existe (o el actor no tiene visibilidad).
conflict	409	Duplicate externalId, versión stale, estado no permitido.
payload_too_large	413	Body > 1 MB (feedback) / > 128 KB (resto).
validation_failed	422	Body válido como JSON pero falla el schema Zod.
rate_limited	429	Sobre el rate de tu tier. Ver headers Retry-After + X-RateLimit-*.
quota_exceeded	429	Sobre el límite de ingestion del plan mensual.
internal_error	500	Bug del server. Queda en logs con correlationId.
method_not_allowed	405	Endpoint solo acepta otros verbos HTTP.

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).

Ingestar un item

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(),
    }],
  }),
});

Leer briefs recientes

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);
}

Algo no te cierra

Si un endpoint no responde como esperás, si falta algo que necesitás o si querés un scope nuevo — escribinos. Priorizamos pedidos con caso de uso real.

Ver /developers overview Crear workspace Hablar con sales

FUVIHUB · loading