Agent Skills

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

@@ -0,0 +1,58 @@
+---
+name: api-development
+description: 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`
+
+On failure, include error message:
+
+```python
+return {"success": False, "error": "Description of what went wrong"}
+```
+
+On success:
+
+```python
+return {"success": True, "data": result}
+```
+
+## 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)