API reference batch 6 — DLP events, DLP stats, session management

This batch documents three endpoint groups used by the admin portal’s DLP incident workflow and session management panel.

DLP events — /api/dlp/events
DLP stats — /api/dlp/stats
Session management — /api/admin/sessions

DLP events

Prefix: /api/dlp/events Auth: Admin JWT (Authorization: Bearer <token>) Tags: dlp-events

DLP events are structured incident records created when the DLP pipeline detects a policy violation. Unlike audit log entries (append-only), DLP events support lifecycle workflow: open → acknowledged → resolved / false_positive.

DLPEventResponse schema

Field	Type	Description
`id`	string (UUID)	Event identifier
`user_id`	string \| null	UUID of the user whose request triggered the event
`conversation_id`	string \| null	UUID of the conversation
`detector_name`	string	Name of the detector that fired (e.g. `"regex:CREDIT_CARD"`)
`entity_type`	string	Entity type label (e.g. `"CREDIT_CARD"`, `"SSN"`, `"PII_EMAIL"`)
`matched_text`	string \| null	The matched text value (may be null if not stored)
`action_taken`	string	Policy action applied (`ALLOW`, `BLOCK`, `REDACT`, `FLAG`)
`status`	string	Lifecycle status: `open`, `acknowledged`, `resolved`, `false_positive`
`severity`	string	`low`, `medium`, `high`, `critical`
`direction`	string	`input` (user prompt) or `output` (model response)
`resolution_notes`	string \| null	Free-text notes added when resolving
`resolved_by`	string \| null	UUID of the admin who resolved the event
`resolved_at`	datetime \| null	When the event was resolved
`created_at`	datetime	When the event was created

POST /api/dlp/events

Create a new DLP event. Used by the DLP pipeline and admin tooling to record detection incidents.

POST /api/dlp/events
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "user_id": "user_01abc123",
  "conversation_id": "conv_01def456",
  "detector_name": "regex:CREDIT_CARD",
  "entity_type": "CREDIT_CARD",
  "matched_text": "4111-****-****-1111",
  "action_taken": "REDACT",
  "direction": "input",
  "severity": "high"
}

Response 201 Created:

{
  "id": "evt_01ghi789",
  "user_id": "user_01abc123",
  "conversation_id": "conv_01def456",
  "detector_name": "regex:CREDIT_CARD",
  "entity_type": "CREDIT_CARD",
  "matched_text": "4111-****-****-1111",
  "action_taken": "REDACT",
  "status": "open",
  "severity": "high",
  "direction": "input",
  "resolution_notes": null,
  "resolved_by": null,
  "resolved_at": null,
  "created_at": "2026-03-12T14:30:00Z"
}

GET /api/dlp/events

List DLP events with optional filters. Results are paginated, newest first.

Query parameters:

Parameter	Type	Description
`status`	string	Filter by lifecycle status (`open`, `acknowledged`, `resolved`, `false_positive`)
`entity_type`	string	Filter by entity type
`severity`	string	Filter by severity (`low`, `medium`, `high`, `critical`)
`direction`	string	`input` or `output`
`user_id`	string	Filter by user UUID
`date_from`	datetime	Events created on or after this datetime (ISO-8601)
`date_to`	datetime	Events created on or before this datetime (ISO-8601)
`page`	integer	Page number (default: 1)
`page_size`	integer	Items per page (default: 50, max: 200)

GET /api/dlp/events?status=open&severity=high&page=1&page_size=25
Authorization: Bearer <admin-token>

Response 200 OK:

{
  "items": [ /* DLPEventResponse[] */ ],
  "total": 142,
  "page": 1,
  "page_size": 25
}

GET /api/dlp/events/summary

Get aggregated summary statistics for DLP events. Useful for dashboard widgets.

GET /api/dlp/events/summary
Authorization: Bearer <admin-token>

Response 200 OK:

{
  "total": 1420,
  "by_status": {
    "open": 38,
    "acknowledged": 12,
    "resolved": 1340,
    "false_positive": 30
  },
  "by_entity_type": {
    "CREDIT_CARD": 210,
    "SSN": 85,
    "PII_EMAIL": 430
  },
  "by_severity": {
    "low": 600,
    "medium": 500,
    "high": 280,
    "critical": 40
  }
}

GET /api/dlp/events/{event_id}

Get a single DLP event by UUID.

GET /api/dlp/events/evt_01ghi789
Authorization: Bearer <admin-token>

Returns a DLPEventResponse or 404 if not found.

PUT /api/dlp/events/{event_id}

Update a DLP event’s lifecycle status and optionally add resolution notes.

When status transitions to resolved or false_positive, the resolved_by and resolved_at fields are set automatically from the authenticated admin’s identity.

PUT /api/dlp/events/evt_01ghi789
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "status": "resolved",
  "resolution_notes": "Confirmed false positive — test credit card data in dev environment"
}

`status` value	Effect
`acknowledged`	Moves event from open queue; sets no resolved_* fields
`resolved`	Marks as resolved; sets `resolved_by` and `resolved_at`
`false_positive`	Marks as a detection error; sets `resolved_by` and `resolved_at`

Returns the updated DLPEventResponse or 404 if not found.

DLP stats

Prefix: /api/dlp Auth: Admin JWT Tags: dlp

GET /api/dlp/stats

Get aggregated DLP detection statistics over a configurable time window. Provides breakdowns not available via the /summary endpoint — notably per-detector counts and daily trend data.

Query parameters:

Parameter	Type	Default	Description
`days`	integer	30	Look-back window in days (1–365)

GET /api/dlp/stats?days=7
Authorization: Bearer <admin-token>

Response 200 OK:

{
  "total_events": 284,
  "by_entity_type": [
    { "entity_type": "CREDIT_CARD", "count": 98 },
    { "entity_type": "PII_EMAIL", "count": 74 }
  ],
  "by_severity": [
    { "severity": "high", "count": 112 },
    { "severity": "medium", "count": 102 }
  ],
  "by_status": [
    { "status": "resolved", "count": 241 },
    { "status": "open", "count": 43 }
  ],
  "by_detector": [
    { "detector_name": "regex:CREDIT_CARD", "count": 98 },
    { "detector_name": "ner:PERSON", "count": 66 }
  ],
  "daily_trend": [
    { "date": "2026-03-06", "count": 32 },
    { "date": "2026-03-07", "count": 41 },
    { "date": "2026-03-08", "count": 38 }
  ]
}

Field	Description
`total_events`	Total detection events in the window
`by_entity_type`	Counts per entity type label, sorted descending
`by_severity`	Counts per severity level, sorted descending
`by_status`	Counts per lifecycle status, sorted descending
`by_detector`	Counts per detector name (regex/ner/ml), sorted descending
`daily_trend`	One entry per day in the window, count of events on that date

Session management

Prefix: /api/admin Auth: Admin JWT Tags: admin

Session management endpoints let admins list active user sessions and force-revoke them. Sessions are JWT-based and tracked in the database. When a session is force-revoked, its JTI (JWT ID) is added to the token blacklist so the corresponding token is immediately invalidated — even before its natural expiry.

SessionResponse schema

Field	Type	Description
`id`	string (UUID)	Session identifier
`user_id`	string	UUID of the session owner
`token_jti`	string	JWT ID claim (unique per issued token)
`ip_address`	string \| null	Client IP at login
`user_agent`	string \| null	Client User-Agent at login
`is_active`	boolean	Whether the session is currently active
`created_at`	datetime	When the session was created (login time)
`expires_at`	datetime	When the JWT token expires

GET /api/admin/sessions

List all active sessions. Optionally filter to a specific user.

Query parameters:

Parameter	Type	Description
`user_id`	UUID	Filter to sessions for a specific user

# All active sessions
GET /api/admin/sessions
Authorization: Bearer <admin-token>

# Sessions for a specific user
GET /api/admin/sessions?user_id=user_01abc123
Authorization: Bearer <admin-token>

Response 200 OK:

{
  "items": [
    {
      "id": "sess_01abc",
      "user_id": "user_01abc123",
      "token_jti": "jti_xyz",
      "ip_address": "203.0.113.50",
      "user_agent": "Mozilla/5.0 ...",
      "is_active": true,
      "created_at": "2026-03-12T08:00:00Z",
      "expires_at": "2026-03-13T08:00:00Z"
    }
  ],
  "total": 1
}

Results are ordered newest first.

DELETE /api/admin/sessions/{session_id}

Force-logout a specific session. The session is deactivated and its JWT is blacklisted immediately.

DELETE /api/admin/sessions/sess_01abc
Authorization: Bearer <admin-token>

Response 200 OK: Returns the deactivated SessionResponse.

404 if no active session with that ID exists.

DELETE /api/admin/users/{user_id}/sessions

Force-logout all active sessions for a specific user. Returns the list of revoked sessions with a count.

DELETE /api/admin/users/user_01abc123/sessions
Authorization: Bearer <admin-token>

Response 200 OK:

{
  "items": [ /* SessionResponse[] */ ],
  "total": 3
}

Use this endpoint when:

A user account is suspected compromised and all tokens must be invalidated
An admin resets a user’s password and wants to force re-authentication
Offboarding: ensure the user cannot continue using existing tokens

Session limit enforcement

The Platform enforces a configurable concurrent session limit per user (default: 5). When a user logs in and would exceed this limit, the oldest active sessions are automatically evicted (FIFO). Evicted sessions are blacklisted immediately.

The limit is configurable system-wide via system_config.max_concurrent_sessions.

API reference: DLP rules — DLP rule CRUD and pattern management
API reference: Compliance reporting — Bundle-level DLP statistics
DLP pipeline configuration — How detection events are generated
Admin guide: MFA — MFA configuration that affects session requirements

API reference batch 6 — DLP events, DLP stats, session management

DLP events

DLPEventResponse schema

POST /api/dlp/events

GET /api/dlp/events

GET /api/dlp/events/summary

GET /api/dlp/events/{event_id}

PUT /api/dlp/events/{event_id}

DLP stats

GET /api/dlp/stats

Session management

SessionResponse schema

GET /api/admin/sessions

DELETE /api/admin/sessions/{session_id}

DELETE /api/admin/users/{user_id}/sessions

Session limit enforcement

Related docs