API · Python

Python guide

The standard library. No extra package. Walk through register or sign-in, create a key, send one ordinary request, read alerts, then the follow-up calls you will need later.

Standard library only. No pip package required for these samples.

Before you start

BASE = "https://api-vigil.bizinvestify.com"
Export VIGIL_API_KEY before calling ingest.
urllib raises on HTTP error status — read message from the JSON body when you catch HTTPError.

Day one in Python

Helper + day-one flow

import json
import os
import urllib.request

BASE = os.environ.get("VIGIL_ENDPOINT", "https://api-vigil.bizinvestify.com")

def vigil(path, method="GET", token=None, api_key=None, body=None):
    data = None if body is None else json.dumps(body).encode()
    request = urllib.request.Request(BASE + path, data=data, method=method)
    request.add_header("accept", "application/json")
    if body is not None:
        request.add_header("content-type", "application/json")
    if token:
        request.add_header("authorization", "Bearer " + token)
    if api_key:
        request.add_header("x-api-key", api_key)
    with urllib.request.urlopen(request) as response:
        payload = json.load(response)
    if not payload.get("success"):
        raise RuntimeError(payload.get("message") or payload.get("error"))
    return payload.get("data")

session = vigil("/api/v1/auth/login", method="POST", body={
    "email": "ada@example.com",
    "password": "Password!234",
})
created = vigil("/api/v1/api-keys", method="POST", token=session["accessToken"], body={
    "name": "Production server",
})
print("Copy this once:", created["apiKey"])

recorded = vigil(
    "/api/v1/ingest",
    method="POST",
    api_key=os.environ.get("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,
    },
)
print(recorded["score"], recorded["alertId"])
print(vigil("/api/v1/alerts?limit=20", token=session["accessToken"]))

More useful calls

Ack an alert

POST with the bearer token only.

vigil("/api/v1/alerts/" + alert_id + "/ack", method="POST", token=session["accessToken"])

Catch a refusal

HTTPError still carries the envelope in the body.

import urllib.error

try:
    vigil("/api/v1/auth/login", method="POST", body={"email": "x", "password": "y"})
except urllib.error.HTTPError as err:
    payload = json.load(err)
    print(payload.get("message") or payload.get("error"))

What success looks like

Ingest

HTTP 202 under the hood; success true when the event was stored.

{"success": true, "data": {"score": 0, "alertId": None}}

Tips

Auth uses Bearer. Ingest uses x-api-key.
Keep secrets in the environment, not in the script file you commit.

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.