# EV Network Intelligence - Anomaly Detection API

> EV charging session anomaly detection as a service.
> Push OCPP meter-value sessions; get back anomaly scores, categories, and confidence.

## Base URL

https://api.solidstudio.ai

## Authentication

Every request requires a Bearer token in the `Authorization` header.
The token encodes the tenant context — no separate tenant header is needed.

## Endpoints

### Sessions

POST /v1/sessions
  Create a charging session with OCPP meter values.
  Runs CSAR-2 pipeline automatically if >= 3 meter values provided.
  Sessions longer than 6 hours are truncated to the last 6h window.
  Returns anomaly score, categories, and confidence per session.
  Responses: 201, 400, 422, 500

PUT  /v1/sessions/{session_id}
  Replace all meter values for a session.
  Auto-runs CSAR-2 if >= 3 meter values after replacement.
  Responses: 200, 404, 422

PATCH /v1/sessions/{session_id}
  Append meter values to an existing session (incremental push).
  Auto-runs CSAR-2 if >= 3 accumulated meter values.
  Responses: 200, 404, 422

GET  /v1/sessions
  List analyzed sessions with pagination and filters.
  Query params: page, page_size, charging_station_id, evse_id, is_anomaly, min_score, min_confidence, date_from, date_to
  Responses: 200, 400, 422

GET  /v1/sessions/{session_id}
  Full session details: meter values, analysis result, anomaly categories.
  Responses: 200, 400, 404, 422

### LLM

POST /v1/sessions/{session_id}/explain
  Get an LLM-generated explanation of session anomalies.
  Responses: 200, 422

POST /v1/sessions/{session_id}/ask
  Ask a natural language question about a specific session.
  Responses: 200, 422

### Batches

POST /v1/sessions/batch
  Submit multiple sessions for async batch analysis. Returns batch_id.
  Responses: 200, 422

GET  /v1/sessions/batch/{batch_id}
  Poll batch processing status and retrieve results.
  Responses: 200, 400, 404, 422

### Stations

GET  /v1/stations
  List stations with aggregated anomaly statistics.
  Query params: page, page_size
  Responses: 200, 422

GET  /v1/stations/{charging_station_id}
  Station details: connectors, energy data, anomaly counts.
  Responses: 200, 404, 422

GET  /v1/stations/{charging_station_id}/connectors
  Per-connector anomaly breakdown by category.
  Responses: 200, 404, 422

GET  /v1/stations/{charging_station_id}/inference
  Latest SHADE inference result for a station.
  Responses: 200, 404, 422

GET  /v1/stations/{charging_station_id}/anomalies
  Station-level anomaly history from SHADE detection.
  Query params: page, page_size
  Responses: 200, 404, 422

### Models

GET  /v1/models
  List available base models and tenant fine-tuned models.
  Responses: 200

GET  /v1/models/{model_id}
  Model details: version, metrics, training date, status.
  Responses: 200, 404, 422

POST /v1/models/fine-tune
  Trigger model fine-tuning on your session data.
  Responses: 200, 422

GET  /v1/models/fine-tune/{job_id}
  Fine-tuning job progress and result model ID.
  Responses: 200, 404, 422

### Statistics

GET  /v1/statistics
  Tenant-wide summary: sessions, anomalies, stations, anomaly rate.
  Responses: 200

### Webhooks

Webhooks are configured via the management dashboard.
When SHADE detects a station-level anomaly, a POST is sent to your URL.

Event: station.anomaly_detected
Payload: charging_station_id, is_anomaly, anomaly_score, detection_details, analyzed_at, webhook_id

## Error format

All non-2xx responses return: {"detail": "human-readable message"}

Common error codes:
  400 - missing or invalid Bearer token
  404 - resource not found
  422 - validation error

## Key schemas

SessionCreateRequest    - session_id, charging_station_id, connector_id, evse_id, meter_values[], metadata
MeterValue              - timestamp, value, measurand, unit, phase, location
SessionAnalysisResponse - session_id, status, is_anomaly, anomaly_score, anomaly_confidence, anomalies[], analyzed_at
AnomalyDetail           - category, score, confidence, bucket_range {start_unit, end_unit}, time_range
ErrorResponse           - {"detail": "..."}

## Anomaly categories

CHARGING_EXPECTED, KWH_DECREASE, UNEXPECTED_KWH_ACCUMULATE, ENERGY_PIT,
INCORRECT_ACTIVE_POWER_REGISTER, UNEXPECTED_CHARGE_LEVEL_CHANGES, ZERO_SESSION

## Resources

- API reference:      https://solidstudio.ai/developers
- OpenAPI JSON:       https://api.solidstudio.ai/openapi.json
- Swagger UI:         https://api.solidstudio.ai/docs
- ReDoc:              https://api.solidstudio.ai/redoc