API Reference

REST API for automation, integration, and programmatic access.

Overview

The VigilPrism API provides programmatic access to all server functionality. Use it to automate audits, integrate with CI/CD pipelines, build custom dashboards, and connect with third-party tools.

Base URL: http://your-server:8000/api/v1

Authentication

All API requests require authentication using JWT tokens or API keys.

1. JWT Token (Recommended)

Obtain a token by logging in, then include it in the Authorization header.

# Login to get token

curl -X POST http://server:8000/api/v1/auth/token \

  -d "username=admin" \

  -d "password=your-password"

# Response

  "access_token": "eyJhbGciOiJIUzI1NiIs...",

  "token_type": "bearer",

  "expires_in": 86400

2. Using the Token

curl http://server:8000/api/v1/systems \

  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

3. API Keys (For Automation)

Generate API keys for long-running integrations. Keys don't expire but can be revoked.

curl http://server:8000/api/v1/systems \

  -H "X-API-Key: vp_1234567890abcdef..."

Interactive API Documentation

VigilPrism includes built-in OpenAPI documentation with interactive testing.

Swagger UI: http://server:8000/docs

ReDoc: http://server:8000/redoc

OpenAPI JSON: http://server:8000/openapi.json

Common Endpoints

GET/systems

List all registered agents/systems

curl http://server:8000/api/v1/systems \

  -H "Authorization: Bearer $TOKEN"

GET/systems/{agent_id}

Get details for a specific system

curl http://server:8000/api/v1/systems/abc123 \

  -H "Authorization: Bearer $TOKEN"

POST/systems/{agent_id}/audit

Trigger a security audit on an agent

curl -X POST http://server:8000/api/v1/systems/abc123/audit \

  -H "Authorization: Bearer $TOKEN" \

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

  -d '{"include_vulnerability_scan": true}'

GET/audits

List audit results with filtering

curl "http://server:8000/api/v1/audits?limit=10&severity=critical" \

  -H "Authorization: Bearer $TOKEN"

GET/compliance/{framework}/status

Get compliance status for a framework (nist, iso27001, soc2, hipaa)

curl http://server:8000/api/v1/compliance/nist/status \

  -H "Authorization: Bearer $TOKEN"

GET/vulnerabilities

List discovered vulnerabilities

curl "http://server:8000/api/v1/vulnerabilities?severity=critical&in_kev=true" \

  -H "Authorization: Bearer $TOKEN"

POST/agents/enrollment-token

Create a new agent enrollment token

curl -X POST http://server:8000/api/v1/agents/enrollment-token \

  -H "Authorization: Bearer $TOKEN" \

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

  -d '{"name": "Production", "expires_days": 7, "max_uses": 50}'

Response Format

All responses are JSON. Successful responses include the requested data, while errors include an error code and message.

Success Response

{
  "status": "success",
  "data": {
    "systems": [...],
    "total": 15,
    "page": 1
  }
}

Error Response

{
  "detail": "Agent not found",
  "error_code": "NOT_FOUND",
  "status_code": 404
}

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created (new resource)
`400`	Bad Request (invalid parameters)
`401`	Unauthorized (missing/invalid token)
`403`	Forbidden (insufficient permissions)
`404`	Not Found
`429`	Rate Limited (too many requests)
`500`	Internal Server Error

Code Examples

Python

import requests

BASE_URL = "http://server:8000/api/v1"

# Login
response = requests.post(f"{BASE_URL}/auth/token", data={
    "username": "admin",
    "password": "your-password"
})
token = response.json()["access_token"]

# Get systems
headers = {"Authorization": f"Bearer {token}"}
systems = requests.get(f"{BASE_URL}/systems", headers=headers)
print(systems.json())

# Trigger audit
audit = requests.post(
    f"{BASE_URL}/systems/abc123/audit",
    headers=headers,
    json={"include_vulnerability_scan": True}
)
print(audit.json())

JavaScript (Node.js)

const BASE_URL = "http://server:8000/api/v1";

// Login
const loginResponse = await fetch(`${BASE_URL}/auth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: "username=admin&password=your-password"
});
const { access_token } = await loginResponse.json();

// Get systems
const systemsResponse = await fetch(`${BASE_URL}/systems`, {
  headers: { "Authorization": `Bearer ${access_token}` }
});
const systems = await systemsResponse.json();
console.log(systems);

PowerShell

$BaseUrl = "http://server:8000/api/v1"

# Login
$body = @{ username = "admin"; password = "your-password" }
$token = (Invoke-RestMethod -Uri "$BaseUrl/auth/token" -Method Post -Body $body).access_token

# Get systems
$headers = @{ Authorization = "Bearer $token" }
$systems = Invoke-RestMethod -Uri "$BaseUrl/systems" -Headers $headers
$systems | ConvertTo-Json

Rate Limiting

API requests are rate limited to prevent abuse. Default limits:

100 requests per IP per minute
1000 requests per user per hour

Rate limit headers are included in responses:

X-RateLimit-Limit: 100

X-RateLimit-Remaining: 95

X-RateLimit-Reset: 1699500000

Webhooks

Configure webhooks to receive real-time notifications when events occur.

Supported Events

audit.completed - Audit finished
vulnerability.critical - Critical CVE found
agent.offline - Agent went offline
compliance.failed - Compliance check failed

Create Webhook

curl -X POST http://server:8000/api/v1/webhooks \

  -H "Authorization: Bearer $TOKEN" \

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

  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["audit.completed", "vulnerability.critical"],
    "secret": "your-webhook-secret"
  }'

Vulnerability Scanning

Back to

Documentation Home