NetAlertX/.github/skills/api-development/SKILL.md

name, description

name	description
api-development	Develop and extend NetAlertX REST API endpoints. Use this when asked to create endpoint, add API route, implement API, or modify API responses.

API Development

Entry Point

Flask app: server/api_server/api_server_start.py

Existing Routes

• /device/<mac> - Single device operations
• /devices - Device list
• /devices/export/{csv,json} - Export devices
• /devices/import - Import devices
• /devices/totals - Device counts
• /devices/by-status - Devices grouped by status
• /nettools - Network utilities
• /events - Event log
• /sessions - Session management
• /dbquery - Database queries
• /metrics - Prometheus metrics
• /sync - Synchronization

Authorization

All routes require header:

Authorization: Bearer <API_TOKEN>

Retrieve token via get_setting_value('API_TOKEN').

Response Contract

MANDATORY: All responses must include "success": true|false

return {"success": False, "error": "Description of what went wrong"}

On success:

return {"success": True, "data": result}

return {"success": False, "error": "Description of what went wrong"}

On success:

return {"success": True, "data": result}

Exception: The legacy /device/<mac> GET endpoint does not follow this contract to maintain backward compatibility with the UI.

Adding New Endpoints

1. Add route in server/api_server/ directory
2. Follow authorization pattern
3. Return proper response contract
4. Update UI to read/write JSON cache (don't bypass pipeline)