Skip to content

api_documentation.md

Latest commit

 

History

History
156 lines (116 loc) · 6.65 KB

api_documentation.md

File metadata and controls

156 lines (116 loc) · 6.65 KB
Raw

Complete SOCMINT.AI API Architecture Blueprint

This document outlines the complete REST API architecture for the SOCMINT backend. It maps out the 60+ endpoints required to interface with all 25 core MongoDB collections.

All protected routes require: Authorization: Bearer <JWT_TOKEN>

1. Authentication & Security Layer

Method Endpoint Description
POST /api/auth/login Authenticate and retrieve JWT session
POST /api/auth/logout Terminate active session
POST /api/auth/mfa/setup Generate TOTP secret for Authenticator apps
POST /api/auth/mfa/verify Verify TOTP code and finalize login
POST /api/auth/password/reset Trigger password reset flow
GET /api/auth/sessions Fetch user's active concurrent sessions
DELETE /api/auth/sessions/:id Revoke a specific session

2. Platform Infrastructure & Health

Method Endpoint Description
GET /health Basic Liveness probe (200 OK)
GET /api/v1/platform/status Comprehensive Ping/Uptime stats across all DBs & Nodes
GET /api/v1/platform/metrics System-wide aggregates (CPU, Storage used, AI Execution count)
GET /api/v1/platform/agents Status of all background AI Agents (Discovery, Correlation, etc.)

3. Organization & Team Management

Method Endpoint Description
GET /api/v1/organizations Fetch all organizations
POST /api/v1/organizations Provision a new Organization
PATCH /api/v1/organizations/:id Update organization details
GET /api/v1/organizations/:id/departments Fetch all departments in an org
POST /api/v1/organizations/:id/departments Create a new department
GET /api/v1/teams Fetch teams (filterable by org/dept)
POST /api/v1/teams Create an investigation team
PATCH /api/v1/teams/:id/members Add/Remove users from a team

4. User & Role Management

Method Endpoint Description
GET /api/v1/users List all users (supports extensive filtering)
GET /api/v1/users/:id Fetch specific user profile
POST /api/v1/users/invite Provision user and generate secure tempPassword
PATCH /api/v1/users/:id Update user details (name, phone, team)
PATCH /api/v1/users/:id/role Escalate or modify user role
PATCH /api/v1/users/:id/suspend Instantly revoke access and terminate sessions
GET /api/v1/roles Fetch available roles and their granular permissions

5. Case Management

Method Endpoint Description
GET /api/v1/cases List cases (RBAC filtered)
POST /api/v1/cases Create a new Case
GET /api/v1/cases/:id Fetch complete Case details and Timeline
PATCH /api/v1/cases/:id Update Case (Priority, Title, Description)
POST /api/v1/cases/:id/members Assign Investigators/Viewers to the Case
PATCH /api/v1/cases/:id/status Mark case as Active, Pending Review, or Closed

6. Investigation & AI Trigger Engine

Method Endpoint Description
POST /api/v1/investigations Submit target identifiers and trigger the AI Pipeline
GET /api/v1/investigations/case/:caseId List all investigation runs for a case
POST /api/v1/investigations/:id/halt Emergency stop a running AI investigation
GET /api/v1/investigations/:id/status Polling endpoint for AI progress (if WebSockets fallback)

7. Intelligence Aggregation (The Results)

These endpoints fetch data populated by the Python/FastAPI AI models.

Method Endpoint Description
GET /api/v1/intelligence/:caseId/profiles Fetch Discovered Profiles from social networks
GET /api/v1/intelligence/:caseId/correlations Fetch Identity Correlations and Confidence Scores
GET /api/v1/intelligence/:caseId/visual Fetch Face matches, Reverse Image matches, EXIF data
GET /api/v1/intelligence/:caseId/content Fetch NLP Keywords, Sentiment, Topics
GET /api/v1/intelligence/:caseId/behavior Fetch Active Hours, Posting Frequency anomalies
GET /api/v1/intelligence/:caseId/network Fetch graph-ready Relationship data (Followers/Mentions)

8. Digital Forensics & Evidence

Method Endpoint Description
GET /api/v1/evidence/case/:caseId List all digital evidence artifacts for a Case
POST /api/v1/evidence Upload evidence (auto-generates SHA-256 Hash)
PATCH /api/v1/evidence/:id/verify DFIR Analyst verifies cryptographic integrity
PATCH /api/v1/evidence/:id/flag Flag evidence as corrupted or irrelevant
GET /api/v1/evidence/:id/chain-of-custody Fetch immutable audit trail of who touched this evidence

9. Report Generation

Method Endpoint Description
GET /api/v1/reports/case/:caseId List reports generated for a case
POST /api/v1/reports/generate Trigger backend PDF generation combining all intelligence
PATCH /api/v1/reports/:id/approve Case Supervisor approves draft report
PATCH /api/v1/reports/:id/reject Reject report and send back to Investigator

10. Audit & Compliance

Method Endpoint Description
GET /api/v1/audit-logs Master audit ledger. Supports deep filtering (Org, Action, Date)
GET /api/v1/audit-logs/export Download CSV of audit logs for legal compliance
GET /api/v1/compliance/retention List closed cases nearing 7-year data retention limit

11. Notifications

Method Endpoint Description
GET /api/v1/notifications Fetch unread notifications for current user
PATCH /api/v1/notifications/:id/read Mark specific notification as read
PATCH /api/v1/notifications/read-all Mark all as read

12. WebSocket Channels (Real-Time)

Requires JWT in Handshake Auth

Event Type Direction Payload Description
investigation:subscribe Client -> Server Join a Case Room case_ID
investigation:progress Server -> Client Streams 0-100% Agent Progress
investigation:complete Server -> Client Fires when pipeline finishes
system:broadcast Client -> Server Send Global Alert (Platform Admins)
organization:broadcast Client -> Server Send Org-Wide Alert (Supervisors)
notification:global Server -> Client Incoming System Alerts