# 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.

- Skill: `netalertx/api-development` (Agent Skill)
- Install (CLI): `npx skillmds@latest add netalertx/api-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/netalertx/api-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: netalertx (https://skillmd.com/u/netalertx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/netalertx/api-development

---


# 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`

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

On success:

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

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

On success:

```python
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)