Skip to content

API_V1_ROUTES.md

Latest commit

 

History

History
175 lines (136 loc) · 4.87 KB

API_V1_ROUTES.md

File metadata and controls

175 lines (136 loc) · 4.87 KB

API v1 Routes Documentation

Overview

The Zen AI Pentest API v1 routes are organized in a modular structure under api/routes/v1/.

Route Structure

api/routes/v1/
├── __init__.py       # Router aggregator
├── auth.py           # Authentication endpoints
├── findings.py       # Findings management
├── health.py         # Health check endpoints
├── notifications.py  # Notification endpoints
├── reports.py        # Report generation
├── scans.py          # Scan management
├── schedules.py      # Scheduled scans
├── settings.py       # Configuration settings
├── stats.py          # Statistics and analytics
├── tools.py          # Tool execution
└── websocket.py      # WebSocket endpoints

Endpoints

Authentication (/api/v1/auth)

Method Endpoint Description
POST /login Login and obtain JWT token
GET /me Get current user info
POST /refresh Refresh access token
GET /csrf-token Get CSRF token
POST /logout Logout user
POST /logout-all Logout from all devices

Scans (/api/v1/scans)

Method Endpoint Description
POST / Create a new scan
GET / List all scans
GET /{scan_id} Get scan details
PATCH /{scan_id} Update scan
DELETE /{scan_id} Delete scan
GET /{scan_id}/findings Get scan findings
POST /{scan_id}/findings Add finding to scan

Findings (/api/v1/findings)

Method Endpoint Description
GET / List all findings
GET /{finding_id} Get finding details
PATCH /{finding_id} Update finding
DELETE /{finding_id} Delete finding

Tools (/api/v1/tools)

Method Endpoint Description
POST /execute Execute a security tool
GET / List available tools

Reports (/api/v1/reports)

Method Endpoint Description
POST / Generate a report
GET / List all reports
GET /{report_id}/download Download report

Schedules (/api/v1/schedules)

Method Endpoint Description
POST / Create scheduled scan
GET / List scheduled scans
GET /{schedule_id} Get schedule details
PATCH /{schedule_id} Update schedule
DELETE /{schedule_id} Delete schedule
POST /{schedule_id}/run Run schedule now

Settings (/api/v1/settings)

Method Endpoint Description
GET /slack Get Slack settings
POST /slack Update Slack settings
GET /jira Get Jira settings
POST /jira Update Jira settings
POST /jira/test Test Jira connection
GET /jira/projects List Jira projects

Stats (/api/v1/stats)

Method Endpoint Description
GET /overview Get overview stats
GET /trends Get scan trends
GET /severity Get severity distribution
GET /tools Get tool usage stats

Notifications (/api/v1/notifications)

Method Endpoint Description
POST /slack/test Test Slack notification
POST /slack/scan-complete Send scan completion notification

Health (/api/v1/health)

Method Endpoint Description
GET /health Health check
GET /info API information

WebSocket (/api/v1/ws)

Method Endpoint Description
WS /scans/{scan_id} Scan updates WebSocket
WS /notifications Notifications WebSocket
WS /agents Agent communication WebSocket
WS /{client_id} Generic client WebSocket

Authentication

All endpoints except health check require authentication via JWT token:

Authorization: Bearer <token>

Response Format

All responses are in JSON format with the following structure:

{
  "status": "success|error",
  "data": {},
  "message": "string"
}

Error Codes

Code Description
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Migration from Legacy API

The v1 routes are designed to replace the legacy endpoints in api/main.py. The migration is ongoing, with new endpoints being added incrementally.

Migration Status

  • ✅ Auth endpoints
  • ✅ Scans endpoints
  • ✅ Findings endpoints
  • ✅ Tools endpoints
  • ✅ Reports endpoints
  • ✅ Schedules endpoints
  • ✅ Settings endpoints
  • ✅ Stats endpoints
  • ✅ Notifications endpoints
  • ✅ Health endpoints
  • ✅ WebSocket endpoints
  • 🔄 Legacy cleanup (in progress)