Insights API

Statux Insights is an AI-powered analytics product that provides automated incident analysis, root cause analysis (RCA) document management, and cross-product incident correlation.

Overview

The Insights API (apps/insights/) runs on port 3003 and is available at insights-api.statux.io.

Core Concepts

Analyses

An Analysis is an AI-generated insight for an incident event:

• Automatically triggered via webhook ingestion from Alerting and Synthetics
• Can also be manually requested by users
• Powered by AWS Bedrock for AI processing
• Tracks analysis events for audit purposes

RCA Documents

A Root Cause Analysis (RCA) document is a structured post-mortem:

• Links to incidents from Alerting and Statuspages products
• Tracks action items with assignees and status
• Supports AI-generated drafts via Bedrock
• Includes statistics and reporting

Webhook Configs

Webhook Configurations control how events flow into Insights:

• Each config generates a unique API key (ins_... prefix)
• Supports optional HMAC-SHA256 signature verification
• Receives events from Synthetics and Alerting products

Usage Budgets

Usage tracking monitors AI analysis consumption:

• Per-organization usage limits
• Configurable budget thresholds
• Usage statistics per organization

Module Structure

apps/insights/src/
├── modules/
│   ├── analysis/          # Incident analysis CRUD and stats
│   ├── rca/               # RCA documents, incidents, action items
│   ├── webhooks/          # Webhook ingestion and config management
│   ├── budget/            # Usage tracking and limits
│   ├── bedrock/           # AWS Bedrock AI integration
│   ├── cache/             # Analysis caching
│   ├── context-builder/   # AI context preparation
│   ├── pre-analysis/      # Pre-processing pipeline
│   ├── validation/        # Input validation
│   ├── audit-logs/        # Activity audit logging
│   └── users/             # User profiles and subscriptions
├── health/                # Health check endpoint
├── entities/              # TypeORM entities
├── migrations/            # Database migrations
└── main.ts                # Application bootstrap

Endpoints

Health

Method	Endpoint	Auth	Description
GET	/api/v1/health	Public	Health check for ALB

Analyses (Incident Insights)

Method	Endpoint	Auth	Description
GET	/api/v1/organizations/:orgId/insights	JWT	List incident insights (paginated)
POST	/api/v1/organizations/:orgId/insights	JWT	Request manual analysis
GET	/api/v1/organizations/:orgId/insights/stats	JWT	Get analysis statistics
GET	/api/v1/organizations/:orgId/insights/:insightId	JWT	Get insight by ID
GET	/api/v1/organizations/:orgId/insights/:insightId/events	JWT	Get events for an insight

RCA Documents

Method	Endpoint	Auth	Description
GET	/api/v1/organizations/:orgId/rcas	JWT	List RCA documents
POST	/api/v1/organizations/:orgId/rcas	JWT	Create RCA document
GET	/api/v1/organizations/:orgId/rcas/stats	JWT	Get RCA statistics
GET	/api/v1/organizations/:orgId/rcas/search-incidents	JWT	Search incidents across products
GET	/api/v1/organizations/:orgId/rcas/:rcaId	JWT	Get RCA by ID
PATCH	/api/v1/organizations/:orgId/rcas/:rcaId	JWT	Update RCA
DELETE	/api/v1/organizations/:orgId/rcas/:rcaId	JWT	Delete RCA
POST	/api/v1/organizations/:orgId/rcas/:rcaId/generate	JWT	Generate AI draft

Incident Links

Method	Endpoint	Auth	Description
GET	/api/v1/organizations/:orgId/rcas/:rcaId/incidents	JWT	List linked incidents
POST	/api/v1/organizations/:orgId/rcas/:rcaId/incidents	JWT	Link incident to RCA
DELETE	/api/v1/organizations/:orgId/rcas/:rcaId/incidents/:linkId	JWT	Unlink incident

Action Items

Method	Endpoint	Auth	Description
GET	/api/v1/organizations/:orgId/rcas/:rcaId/action-items	JWT	List action items
POST	/api/v1/organizations/:orgId/rcas/:rcaId/action-items	JWT	Create action item
PATCH	/api/v1/organizations/:orgId/rcas/:rcaId/action-items/:itemId	JWT	Update action item
DELETE	/api/v1/organizations/:orgId/rcas/:rcaId/action-items/:itemId	JWT	Delete action item

Webhook Configuration

Method	Endpoint	Auth	Description
GET	/api/v1/organizations/:orgId/webhook-configs	JWT	List webhook configs
POST	/api/v1/organizations/:orgId/webhook-configs	JWT	Create webhook config
GET	/api/v1/organizations/:orgId/webhook-configs/:configId	JWT	Get webhook config
PATCH	/api/v1/organizations/:orgId/webhook-configs/:configId	JWT	Update webhook config
DELETE	/api/v1/organizations/:orgId/webhook-configs/:configId	JWT	Delete webhook config
POST	/api/v1/organizations/:orgId/webhook-configs/:configId/regenerate-key	JWT	Regenerate API key

Webhook Ingestion

Method	Endpoint	Auth	Description
POST	/api/v1/webhooks/ingest/:apiKey	Public (API Key)	Ingest webhook event

The ingestion endpoint accepts events from Synthetics and Alerting products. An optional x-webhook-signature header can be provided for HMAC-SHA256 payload verification.

Usage

Method	Endpoint	Auth	Description
GET	/api/v1/organizations/:orgId/usage	JWT	Get usage statistics
PATCH	/api/v1/organizations/:orgId/usage	JWT	Update usage limits

Users

Method	Endpoint	Auth	Description
GET	/api/v1/users/me	JWT	Get current user profile
PATCH	/api/v1/users/me	JWT	Update user profile
GET	/api/v1/users/me/notifications	JWT	Get notification preferences
PATCH	/api/v1/users/me/notifications	JWT	Update notification preferences
GET	/api/v1/users/me/subscription	JWT	Get subscription status
POST	/api/v1/users/me/subscription/checkout	JWT	Initiate checkout
POST	/api/v1/users/me/subscription/portal	JWT	Get billing portal link
GET	/api/v1/organizations/:orgId/users	JWT	List users in organization
POST	/api/v1/organizations/:orgId/users/invite	JWT	Invite user to organization

Key Entities

Analysis Entity

@Entity({ schema: 'insights', name: 'analyses' })
export class Analysis extends BaseEntity {
  organizationId: string;
  incidentId: string;
  status: string;          // pending, processing, completed, failed
  summary: string;
  rootCause: string;
  recommendations: string;
  severity: string;
  sourceProduct: string;   // alerting, synthetics
}

RCA Entity

@Entity({ schema: 'insights', name: 'rcas' })
export class Rca extends BaseEntity {
  organizationId: string;
  title: string;
  status: string;          // draft, in_review, published
  summary: string;
  rootCause: string;
  impact: string;
  timeline: string;
  createdBy: string;
}

Database

Uses the insights schema in PostgreSQL. All entities follow the snake_case naming convention for database columns.

Key Tables

Table	Purpose
analyses	AI-generated incident insights
analysis_events	Analysis processing events
rcas	Root cause analysis documents
rca_incident_links	Links between RCAs and incidents
rca_action_items	Action items for RCAs
webhook_configs	Webhook ingestion configurations
cache_entries	Analysis result caching
tenant_budgets	Per-org usage budgets
users	Organization user access
audit_logs	Activity audit trail

Testing

Run tests with:

npm run test:insights