78 lines
2.9 KiB
Markdown
78 lines
2.9 KiB
Markdown
# IPAM API v2
|
|
|
|
All endpoints are JSON under `/api/v2`. The Vue SPA uses **session cookies** (`credentials: include`); automation uses **API keys** (`X-API-Key`, `Authorization: Bearer`, or `?api_key=`).
|
|
|
|
## Authentication
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| POST | `/api/v2/auth/login` | `{ email, password }` → `{ ok }` or `{ requires_2fa }` / `{ requires_setup }` |
|
|
| POST | `/api/v2/auth/verify-2fa` | `{ code, use_backup? }` |
|
|
| POST | `/api/v2/auth/setup-2fa` | `{ action: "generate" \| "verify", code? }` |
|
|
| POST | `/api/v2/auth/logout` | Clear session |
|
|
| GET | `/api/v2/auth/me` | User, permissions, org branding |
|
|
|
|
## Account
|
|
|
|
| Method | Endpoint |
|
|
|--------|----------|
|
|
| GET | `/api/v2/account` |
|
|
| POST | `/api/v2/account/change-password` |
|
|
| POST | `/api/v2/account/disable-2fa` |
|
|
| POST | `/api/v2/account/regenerate-backup-codes` |
|
|
|
|
## List response format
|
|
|
|
List endpoints return `{ "items": [...] }`. Exceptions:
|
|
|
|
- **Audit log** — `{ "items": [...], "total": N }` (supports pagination)
|
|
- **Devices by tag** — `{ "items": [...], "meta": { "tag_name", "count" } }`
|
|
- **Single resources** (device, subnet, rack) — flat object, not wrapped in `items`
|
|
|
|
## Core resources
|
|
|
|
| Resource | Endpoints |
|
|
|----------|-----------|
|
|
| Dashboard | `GET /api/v2/dashboard` |
|
|
| Search | `GET /api/v2/search?q=` |
|
|
| Devices | CRUD + `/ips`, `/tags`, `/ip-history`, `/custom-fields` |
|
|
| Subnets | CRUD + `/available-ips`, `/next_free_ip`, `/export`, `/dhcp`, `/custom-fields` |
|
|
| IP addresses | `PATCH /api/v2/ip-addresses/{id}` (notes) |
|
|
| IP history | `GET /api/v2/ips/{ip}/history` |
|
|
| Tags | CRUD + device tag assign/remove |
|
|
| Racks | CRUD + `/devices`, `/export` |
|
|
| Custom fields | CRUD + `POST /custom-fields/reorder` |
|
|
| Audit | `GET /audit`, `GET /audit/actions`, `GET /audit/export` |
|
|
| Users & roles | CRUD + `POST /users/{id}/regenerate-api-key` |
|
|
| Permissions | `GET /permissions` |
|
|
| Bulk | `POST /bulk/assign-ips`, `/create-devices`, `/assign-tags`, `/export-subnets` |
|
|
|
|
### Subnet IP helpers
|
|
|
|
- `GET /api/v2/subnets/{id}/available-ips` — unassigned IPs outside DHCP pools
|
|
- `GET /api/v2/subnets/{id}/next_free_ip` — first available IP (also excludes DHCP pools)
|
|
|
|
### Audit query parameters
|
|
|
|
| Param | Description |
|
|
|-------|-------------|
|
|
| `limit` | Page size (default 100) |
|
|
| `offset` | Offset for pagination (default 0) |
|
|
| `user` | Filter by user name (partial match) |
|
|
| `action` | Exact action match (see `GET /audit/actions` for values) |
|
|
| `from` | Start date (`YYYY-MM-DD`) |
|
|
| `to` | End date (`YYYY-MM-DD`) |
|
|
|
|
Export (`GET /audit/export`) accepts the same filter params.
|
|
|
|
See route handlers in `app.py` for required permissions and request bodies.
|
|
|
|
## Example
|
|
|
|
```bash
|
|
curl -H "X-API-Key: YOUR_KEY" https://host/api/v2/devices
|
|
curl -c cookies.txt -X POST -H "Content-Type: application/json" \
|
|
-d '{"email":"admin@example.com","password":"password"}' \
|
|
https://host/api/v2/auth/login
|
|
```
|