From 73d04cae5e0d82a017b0985fed5f4c58fdd0a305 Mon Sep 17 00:00:00 2001 From: Phillip Tarrant Date: Wed, 19 Nov 2025 22:06:38 -0600 Subject: [PATCH] Update API documentation for database-based configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix config_id references to use integers instead of file paths - Update scan delete response format to include scan_id field - Add missing read_only field to Settings API responses - Add missing template fields to Webhook responses - Correct endpoint count from 80+ to 65+ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/API_REFERENCE.md | 44 ++++++++++++++++++++++++++++--------------- 1 file changed, 29 insertions(+), 15 deletions(-) diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index 2980523..46f1336 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -720,7 +720,7 @@ Retrieve a paginated list of scans with optional status filtering. "duration": 125.5, "status": "completed", "title": "Production Network Scan", - "config_id": "/app/configs/production.yaml", + "config_id": 1, "triggered_by": "manual", "started_at": "2025-11-14T10:30:00Z", "completed_at": "2025-11-14T10:32:05Z" @@ -731,7 +731,7 @@ Retrieve a paginated list of scans with optional status filtering. "duration": 98.2, "status": "completed", "title": "Development Network Scan", - "config_id": "/app/configs/dev.yaml", + "config_id": 2, "triggered_by": "scheduled", "started_at": "2025-11-13T15:00:00Z", "completed_at": "2025-11-13T15:01:38Z" @@ -793,7 +793,7 @@ Retrieve complete details for a specific scan, including all sites, IPs, ports, "duration": 125.5, "status": "completed", "title": "Production Network Scan", - "config_id": "/app/configs/production.yaml", + "config_id": 1, "json_path": "/app/output/scan_report_20251114_103000.json", "html_path": "/app/output/scan_report_20251114_103000.html", "zip_path": "/app/output/scan_report_20251114_103000.zip", @@ -968,7 +968,8 @@ Delete a scan and all associated files (JSON, HTML, ZIP, screenshots). **Success Response (200 OK):** ```json { - "message": "Scan 42 deleted successfully" + "scan_id": 42, + "message": "Scan deleted successfully" } ``` @@ -1111,7 +1112,7 @@ Retrieve a list of all schedules with pagination and filtering. { "id": 1, "name": "Daily Production Scan", - "config_id": "/app/configs/prod-scan.yaml", + "config_id": 1, "cron_expression": "0 2 * * *", "enabled": true, "created_at": "2025-11-01T10:00:00Z", @@ -1157,7 +1158,7 @@ Retrieve details for a specific schedule including execution history. { "id": 1, "name": "Daily Production Scan", - "config_id": "/app/configs/prod-scan.yaml", + "config_id": 1, "cron_expression": "0 2 * * *", "enabled": true, "created_at": "2025-11-01T10:00:00Z", @@ -1201,7 +1202,7 @@ Create a new scheduled scan. ```json { "name": "Daily Production Scan", - "config_id": "/app/configs/prod-scan.yaml", + "config_id": 1, "cron_expression": "0 2 * * *", "enabled": true } @@ -1215,7 +1216,7 @@ Create a new scheduled scan. "schedule": { "id": 1, "name": "Daily Production Scan", - "config_id": "/app/configs/prod-scan.yaml", + "config_id": 1, "cron_expression": "0 2 * * *", "enabled": true, "created_at": "2025-11-01T10:00:00Z" @@ -1236,7 +1237,7 @@ Create a new scheduled scan. ```bash curl -X POST http://localhost:5000/api/schedules \ -H "Content-Type: application/json" \ - -d '{"name":"Daily Scan","config_id":"/app/configs/prod.yaml","cron_expression":"0 2 * * *"}' \ + -d '{"name":"Daily Scan","config_id":1,"cron_expression":"0 2 * * *"}' \ -b cookies.txt ``` @@ -1270,7 +1271,7 @@ Update an existing schedule. "schedule": { "id": 1, "name": "Updated Schedule Name", - "config_id": "/app/configs/prod-scan.yaml", + "config_id": 1, "cron_expression": "0 3 * * *", "enabled": false, "updated_at": "2025-11-15T10:00:00Z" @@ -1512,7 +1513,7 @@ Get historical trend data for scans with the same configuration. ], "labels": ["2025-11-10 12:00", "2025-11-15 12:00"], "port_counts": [25, 26], - "config_id": "/app/configs/prod-scan.yaml" + "config_id": 1 } ``` @@ -1632,7 +1633,8 @@ Retrieve a specific setting by key. { "status": "success", "key": "smtp_server", - "value": "smtp.gmail.com" + "value": "smtp.gmail.com", + "read_only": false } ``` @@ -2342,6 +2344,9 @@ List all configured webhooks with pagination. "severity_filter": ["critical", "warning"], "timeout": 10, "retry_count": 3, + "template": null, + "template_format": "json", + "content_type_override": null, "created_at": "2025-11-18T10:00:00Z", "updated_at": "2025-11-18T10:00:00Z" } @@ -2393,6 +2398,9 @@ Get details for a specific webhook. "severity_filter": ["critical"], "timeout": 10, "retry_count": 3, + "template": null, + "template_format": "json", + "content_type_override": null, "created_at": "2025-11-18T10:00:00Z", "updated_at": "2025-11-18T10:00:00Z" } @@ -2475,6 +2483,9 @@ Create a new webhook configuration. "custom_headers": null, "timeout": 10, "retry_count": 3, + "template": null, + "template_format": "json", + "content_type_override": null, "created_at": "2025-11-18T10:00:00Z" } } @@ -2577,6 +2588,9 @@ Update an existing webhook configuration. "custom_headers": null, "timeout": 15, "retry_count": 3, + "template": null, + "template_format": "json", + "content_type_override": null, "updated_at": "2025-11-18T11:00:00Z" } } @@ -3310,9 +3324,9 @@ API versioning will be implemented in future releases. The API is considered sta - **Webhooks API** - Webhook management, delivery tracking, authentication support, retry logic ### Endpoint Count -- Total endpoints: 80+ -- Authenticated endpoints: 75+ -- Public endpoints: 5 (login, setup, health checks) +- Total endpoints: 65+ +- Authenticated endpoints: 60+ +- Public endpoints: 5 (login, setup, health checks for scans/schedules/settings/alerts/webhooks) --- -- 2.49.1