API Reference

Base URL: https://api.netsenx.com/api/v1

Authentication

All endpoints require a Bearer token (JWT) from Supabase Auth:

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.netsenx.com/api/v1/alerts/

Agent endpoints use license-key-based authentication via the /agents/auth endpoint.

Alerts

List Alerts

GET /alerts/

Query Parameters:

Parameter	Type	Description
severity	string	Filter by severity: CRITICAL, HIGH, MEDIUM, LOW
status	string	Filter by status: open, reviewed, resolved, false_positive
rule	string	Filter by rule name
limit	integer	Results per page (default: 30, max: 100)
offset	integer	Pagination offset

Response:

{
  "alerts": [
    {
      "id": "uuid",
      "severity": "HIGH",
      "rule_name": "PORT_SCAN",
      "source_ip": "192.168.1.100",
      "dest_ip": "10.0.0.5",
      "port": 22,
      "protocol": "TCP",
      "score": 0.87,
      "timestamp": 1711900800,
      "status": "open",
      "shap_json": { ... }
    }
  ],
  "total": 142
}

Get Alert Detail

GET /alerts/{alert_id}

Update Alert

PUT /alerts/{alert_id}

Body:

{
  "status": "reviewed",
  "notes": "Investigated, appears legitimate"
}

Agents

Exchange License Key for JWT

POST /agents/auth

Body:

{
  "license_key": "nsx_...",
  "agent_id": "hostname-abc123",
  "hostname": "webserver-01",
  "os_type": "linux",
  "agent_version": "1.2.0"
}

Agent Heartbeat

POST /agents/heartbeat

Sent every 60 seconds by the agent. Returns license status and update availability.

Get Agent Config

GET /agents/config

Returns current detection configuration including rule overrides and IP whitelist.

Check Agent Version

GET /agents/version

Returns the latest available agent version for auto-update.

Analytics

Summary

GET /analytics/summary

Returns aggregate metrics: total alerts, average response time, false positive rate.

Alerts Over Time

GET /analytics/alerts-over-time?days=30

Severity Distribution

GET /analytics/severity-distribution

Top Rules

GET /analytics/top-rules?limit=10

Device Risk Scores

GET /analytics/device-risk

Compliance

NIS2 Readiness Status

GET /compliance/status

Returns 8 readiness checks with pass/fail status and overall score.

Save Compliance Settings

PUT /compliance/settings

Body:

{
  "csirt_contact": "csirt@example.es",
  "irp_reference": "IRP-2024-v3.pdf",
  "supply_chain_assessed": true
}

Reports

Generate NIS2 Art.23 PDF

POST /reports/nis2

Body:

{
  "alert_id": "uuid"
}

Generate GDPR Art.33 PDF

POST /reports/gdpr

Billing

Current Subscription

GET /billing/subscription

Create Checkout Session

POST /billing/checkout

Body:

{
  "plan": "professional",
  "billing_cycle": "annual"
}

Create Portal Session

POST /billing/portal

Returns a Stripe Customer Portal URL for managing payment methods and invoices.

Settings

Audit Log

GET /settings/audit-log?limit=30&offset=0

IP Whitelist

GET /settings/whitelist
POST /settings/whitelist
DELETE /settings/whitelist/{entry_id}

Decision Traces

List Traces

GET /traces/?limit=20&offset=0&search=port+scan

Get Trace Detail

GET /traces/{trace_id}

Download Proof Trail

GET /traces/{trace_id}/proof-trail

Returns JSON proof trail for auditing and regulatory submission.

GDPR Data Access

Export All Data

GET /tenant/export

Returns a ZIP archive containing all tenant data (alerts, traces, rules, settings).

Delete Account

DELETE /tenant

Permanently deletes all tenant data. This action is irreversible.

Rate Limits

Endpoint Category	Limit
General API	100 req/min
Agent heartbeat	2 req/min per agent
Report generation	10 req/hour
Data export	1 req/hour

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1711900860

Errors

All errors follow this format:

{
  "detail": "Human-readable error message"
}

Status Code	Meaning
400	Bad request (validation error)
401	Unauthorized (missing or invalid JWT)
403	Forbidden (insufficient permissions)
404	Resource not found
423	Locked (license expired, account locked)
429	Rate limited
502	External service error (Stripe, etc.)