API · curl

curl guide

A terminal call you can paste and run. Walk through register or sign-in, create a key, send one ordinary request, read alerts, then the follow-up calls you will need later.

Paste these into a terminal. Replace ACCESS_TOKEN and the API key with values from earlier steps. A quiet product search is stored and does not open an alert.

Before you start

Vigil API is at https://api-vigil.bizinvestify.com. Change that host if you deploy elsewhere.
You need curl and a way to copy JSON fields (jq is optional).
Never put the ingest API key in a public web page or commit it to git.
Every answer uses the same envelope: success, data or error, message, timestamp.

Day one in curl

1. Open a workspace

Creates your business and admin account. You start on a 14-day Starter trial. Save accessToken and refreshToken from data.

curl -s https://api-vigil.bizinvestify.com/api/v1/auth/register \
  -H "content-type: application/json" \
  -d '{"email":"ada@example.com","password":"Password!234","organizationName":"Ada Ltd"}'

Already registered? Sign in

Same tokens come back. Use this instead of register when the email already exists.

curl -s https://api-vigil.bizinvestify.com/api/v1/auth/login \
  -H "content-type: application/json" \
  -d '{"email":"ada@example.com","password":"Password!234"}'

2. Create an API key

Paste ACCESS_TOKEN from step 1. data.apiKey is shown once. Copy it into VIGIL_API_KEY and keep it on the server only.

curl -s https://api-vigil.bizinvestify.com/api/v1/api-keys \
  -H "content-type: application/json" \
  -H "authorization: Bearer ACCESS_TOKEN" \
  -d '{"name":"Production server"}'

# Then on the machine that will call ingest:
export VIGIL_API_KEY=vgl_live_PASTE_THE_KEY

3. Tell Vigil about one request

Your app already answered the visitor. This is a cleaned-up note, not a proxy. HTTP 202 and success: true mean it was stored. alertId is null while the score stays under 50.

curl -s -D - https://api-vigil.bizinvestify.com/api/v1/ingest \
  -H "content-type: application/json" \
  -H "x-api-key: $VIGIL_API_KEY" \
  -d '{"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}'

4. Read alerts

An empty list means nothing has scored 50 yet. When something looks suspicious, the list fills and the dashboard Alerts tab shows the same items.

curl -s "https://api-vigil.bizinvestify.com/api/v1/alerts?limit=20" \
  -H "authorization: Bearer ACCESS_TOKEN"

More useful calls

Refresh the access token

Access tokens last 15 minutes. Each refresh returns a new refresh token; the old one stops working.

curl -s https://api-vigil.bizinvestify.com/api/v1/auth/refresh \
  -H "content-type: application/json" \
  -d '{"refreshToken":"vgr_PASTE"}'

Mark an alert as seen

Use the alert id from the alerts list or from ingest when alertId is set.

curl -s -X POST https://api-vigil.bizinvestify.com/api/v1/alerts/ALERT_ID/ack \
  -H "authorization: Bearer ACCESS_TOKEN"

List events

Every ingest call lands here, quiet or not. Useful to confirm the middleware is talking.

curl -s "https://api-vigil.bizinvestify.com/api/v1/events?limit=20" \
  -H "authorization: Bearer ACCESS_TOKEN"

Set a webhook (Growth and Scale)

Must be a public https:// URL. Empty url clears it. Starter cannot enable webhooks.

curl -s -X PUT https://api-vigil.bizinvestify.com/api/v1/settings/webhook \
  -H "content-type: application/json" \
  -H "authorization: Bearer ACCESS_TOKEN" \
  -d '{"url":"https://example.com/vigil"}'

Read the Naira price list

Public. Amounts are monthly, in kobo (100 kobo = ₦1). No sign-in needed.

curl -s https://api-vigil.bizinvestify.com/api/v1/plans

Start a Paystack checkout

Pick a plan id from /api/v1/plans. Amount comes back in kobo, currency NGN. Leave PAYSTACK_SECRET_KEY empty in local dev if checkout is not wired yet.

curl -s https://api-vigil.bizinvestify.com/api/v1/billing/checkout \
  -H "content-type: application/json" \
  -H "authorization: Bearer ACCESS_TOKEN" \
  -d '{"planId":"PLAN_UUID"}'

What success looks like

Register or login

HTTP 200. Register also returns a short welcome message about the Starter trial.

{
  "success": true,
  "data": {
    "accessToken": "eyJ...",
    "refreshToken": "vgr_...",
    "expiresIn": 900,
    "user": {
      "email": "ada@example.com",
      "role": "admin",
      "organizationName": "Ada Ltd"
    }
  }
}

Create a key

HTTP 200. apiKey appears only in this answer.

{
  "success": true,
  "message": "Copy this key now. Vigil will not show it again.",
  "data": {
    "name": "Production server",
    "prefix": "vgl_live_ab12cd34",
    "apiKey": "vgl_live_shown_once"
  }
}

Ingest

HTTP 202. score 0 and alertId null means a quiet request.

{
  "success": true,
  "message": "Event recorded.",
  "data": {
    "eventId": "uuid",
    "score": 0,
    "matchedRuleIds": [],
    "alertId": null
  }
}

When something is wrong

Show message to a person. error is the short code for programs.

{
  "success": false,
  "error": "invalid_api_key",
  "message": "That API key is wrong or revoked.",
  "timestamp": "2026-11-15T12:00:00.000Z"
}

Tips

If success is false, stop and show message. Do not retry blindly with the same bad key.
Ingest uses x-api-key. Dashboard routes use Authorization: Bearer.
plan_inactive means the trial ended or billing lapsed. Open Billing on the site.
Prefer @vigil/sdk on Express or Fastify so you do not hand-roll ingest on every route.

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.