API · Node.js

Node.js guide

Server fetch for Node 18 or newer. Walk through register or sign-in, create a key, send one ordinary request, read alerts, then the follow-up calls you will need later.

Node 18+ has fetch built in. Run this on the server that already answered the visitor. Prefer @vigil/sdk middleware for day-to-day Express or Fastify apps.

Before you start

Set VIGIL_ENDPOINT=https://api-vigil.bizinvestify.com (or your deployed API).
Keep VIGIL_API_KEY in the environment, never in the repo.
If success is false, throw or return payload.message.

Day one in Node.js

Helper + day-one flow

Register (or login), create a key, ingest one ordinary request, then list alerts. Copy the printed apiKey into VIGIL_API_KEY before the ingest call in production.

const base = process.env.VIGIL_ENDPOINT || "https://api-vigil.bizinvestify.com";

async function vigil(path, { method = "GET", token, apiKey, body } = {}) {
  const headers = { accept: "application/json" };
  if (body) headers["content-type"] = "application/json";
  if (token) headers.authorization = `Bearer ${token}`;
  if (apiKey) headers["x-api-key"] = apiKey;
  const response = await fetch(base + path, {
    method,
    headers,
    body: body ? JSON.stringify(body) : undefined,
  });
  const payload = await response.json();
  if (!payload.success) throw new Error(payload.message || payload.error);
  return payload.data;
}

const session = await vigil("/api/v1/auth/register", {
  method: "POST",
  body: {
    email: "ada@example.com",
    password: "Password!234",
    organizationName: "Ada Ltd",
  },
});

const created = await vigil("/api/v1/api-keys", {
  method: "POST",
  token: session.accessToken,
  body: { name: "Production server" },
});
console.log("Copy this once:", created.apiKey);

const recorded = await vigil("/api/v1/ingest", {
  method: "POST",
  apiKey: process.env.VIGIL_API_KEY || created.apiKey,
  body: {
    method: "GET",
    path: "/products",
    query: "q=shoes",
    statusCode: 200,
    ip: "102.89.1.20",
    userAgent: "Mozilla/5.0",
    headers: { host: "shop.example", accept: "application/json" },
    durationMs: 18,
    authFailed: false,
  },
});
console.log(recorded.score, recorded.alertId);

const alerts = await vigil("/api/v1/alerts?limit=20", {
  token: session.accessToken,
});
console.log(alerts);

More useful calls

Sign in instead of register

Same session shape when the email already exists.

const session = await vigil("/api/v1/auth/login", {
  method: "POST",
  body: { email: "ada@example.com", password: "Password!234" },
});

Ack an alert

Pass the alert id from the list or from ingest.

await vigil("/api/v1/alerts/" + alertId + "/ack", {
  method: "POST",
  token: session.accessToken,
});

Express middleware (recommended)

Lets Vigil hear about every response without hand-calling ingest.

import express from "express";
import { vigilExpress } from "@vigil/sdk";

const app = express();
app.use(express.json());
app.use(
  vigilExpress({
    apiKey: process.env.VIGIL_API_KEY,
    endpoint: process.env.VIGIL_ENDPOINT || "https://api-vigil.bizinvestify.com",
  }),
);

What success looks like

Ingest data

Same fields whether you call fetch or use the SDK.

{ eventId, score, matchedRuleIds, alertId }

Tips

Ingest is server-to-server. Do not expose VIGIL_API_KEY to the browser.
Access tokens expire in 15 minutes; refresh with /api/v1/auth/refresh.
For production Node apps, install @vigil/sdk and use the Install tab snippets.

Prefer the dashboard for day-to-day work. Prefer these language pages when you wire by hand. The interactive operator reference stays on the console at https://api-vigil.bizinvestify.com/docs.

New here? Open a workspace on the site, create a key under API keys, then come back and run step 3.