Skip to content

API‐Reference

Jump to bottom
DHANUSH G edited this page Mar 4, 2026 · 1 revision

📊 API Reference

Back to Home | Setup-Guide | Contributing

Base URL: http://localhost:8000 Interactive Docs: http://localhost:8000/docs

📋 Endpoints Summary

Method Endpoint Description Auth
GET / Health check None
POST /logs/ Ingest a new log entry None
GET /logs/ Retrieve logs with pagination None
POST /predict/ Get AI anomaly score None

🟢 GET /

Health check endpoint. Returns the API status.

Request

GET http://localhost:8000/

Response

{
  "status": "healthy",
  "message": "AI Security Monitoring Platform is running"
}
Field Type Description
status string API health status
message string Informational message

Status Codes

Code Meaning
200 OK API is healthy

🟡 POST /logs/

Ingest a new security log entry. The entry is persisted to the database.

Request

POST http://localhost:8000/logs/
Content-Type: application/json

Request Body

{
  "source_ip": "192.168.1.10",
  "destination_ip": "10.0.0.5",
  "protocol": "TCP",
  "bytes_transferred": 5120,
  "event_type": "normal",
  "details": "Regular HTTP request to internal server"
}

Request Fields

Field Type Required Description
source_ip string Yes Source IP address of the traffic
destination_ip string Yes Destination IP address
protocol string Yes Network protocol (e.g., TCP, UDP, ICMP)
bytes_transferred integer Yes Number of bytes in the packet/session
event_type string Yes Classification: normal, suspicious, critical
details string No Additional human-readable description

Response (201 Created)

{
  "id": 42,
  "source_ip": "192.168.1.10",
  "destination_ip": "10.0.0.5",
  "protocol": "TCP",
  "bytes_transferred": 5120,
  "event_type": "normal",
  "details": "Regular HTTP request to internal server",
  "timestamp": "2026-03-04T11:00:00.000Z"
}

Status Codes

Code Meaning
200 OK / 201 Created Log successfully ingested
422 Unprocessable Entity Validation error (missing/invalid fields)

Example cURL

curl -X POST http://localhost:8000/logs/ \
  -H "Content-Type: application/json" \
  -d '{
    "source_ip": "192.168.1.10",
    "destination_ip": "10.0.0.5",
    "protocol": "TCP",
    "bytes_transferred": 5120,
    "event_type": "normal",
    "details": "test entry"
  }'

🟢 GET /logs/

Retrieve recent log entries. Supports pagination via query parameters.

Request

GET http://localhost:8000/logs/?skip=0&limit=20

Query Parameters

Parameter Type Default Description
skip integer 0 Number of records to skip (offset)
limit integer 100 Maximum number of records to return

Response (200 OK)

[
  {
    "id": 1,
    "source_ip": "192.168.1.10",
    "destination_ip": "10.0.0.5",
    "protocol": "TCP",
    "bytes_transferred": 5120,
    "event_type": "normal",
    "details": "Regular request",
    "timestamp": "2026-03-04T10:45:00.000Z"
  },
  ...
]

Status Codes

Code Meaning
200 OK Logs returned successfully
422 Unprocessable Entity Invalid query parameters (e.g., non-integer skip)

Example cURL

# Get first 10 logs
curl http://localhost:8000/logs/?skip=0&limit=10

# Get next page
curl http://localhost:8000/logs/?skip=10&limit=10

🟠 POST /predict/

Submit network traffic features to the AI model and receive an anomaly score and threat classification.

Request

POST http://localhost:8000/predict/
Content-Type: application/json

Request Body

{
  "source_ip": "192.168.1.10",
  "destination_ip": "10.0.0.5",
  "protocol": "TCP",
  "bytes_transferred": 999999,
  "event_type": "suspicious"
}

Response (200 OK)

{
  "anomaly_score": -0.42,
  "is_anomaly": true,
  "threat_level": "critical",
  "confidence": 0.89,
  "message": "High-confidence anomaly detected. Immediate review recommended."
}

Response Fields

Field Type Description
anomaly_score float Isolation Forest score (lower = more anomalous)
is_anomaly boolean true if classified as anomalous
threat_level string normal, suspicious, or critical
confidence float Model confidence (0.0 – 1.0)
message string Human-readable summary

Status Codes

Code Meaning
200 OK Prediction returned
503 Service Unavailable ML model not loaded (run train_model.py first)
422 Unprocessable Entity Validation error

🚨 Error Response Format

All validation errors follow the FastAPI/Pydantic standard format:

{
  "detail": [
    {
      "loc": ["body", "source_ip"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

🧪 Testing the API

You can test all endpoints using the built-in Swagger UI:

  1. Start the backend: uvicorn backend.main:app --reload
  2. Open http://localhost:8000/docs
  3. Click on any endpoint → Try it out → Execute

Or run the pytest test suite:

export PYTHONPATH=.
pytest backend/tests/ -v

Back to Home | Setup-Guide | Contributing

Clone this wiki locally