geutebruck-api/docs/api-reference.md

Geutebruck Cross-Switching API Reference

Overview

REST API for Geutebruck GeViScope/GeViSoft cross-switching control. Route cameras to monitors via simple HTTP endpoints.

Base URL: http://localhost:8000 API Version: 1.0.0 Authentication: JWT Bearer tokens

Quick Links

• Interactive Docs: http://localhost:8000/docs (Swagger UI)
• Alternative Docs: http://localhost:8000/redoc (ReDoc)
• Health Check: http://localhost:8000/health
• Metrics: http://localhost:8000/metrics

---

Authentication

POST /api/v1/auth/login

Authenticate and receive JWT tokens.

Request:

{
  "username": "admin",
  "password": "admin123"
}

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "uuid",
    "username": "admin",
    "role": "administrator"
  }
}

POST /api/v1/auth/logout

Logout (blacklist token).

Headers: Authorization: Bearer {access_token}

Response (200 OK):

{
  "message": "Successfully logged out"
}

GET /api/v1/auth/me

Get current user information.

Headers: Authorization: Bearer {access_token}

---

Cameras

GET /api/v1/cameras

List all cameras.

Headers: Authorization: Bearer {access_token} Required Role: Viewer+

Response (200 OK):

{
  "cameras": [
    {
      "id": 1,
      "name": "Entrance Camera",
      "description": "Main entrance",
      "has_ptz": true,
      "has_video_sensor": true,
      "status": "online"
    }
  ],
  "total": 1
}

GET /api/v1/cameras/{camera_id}

Get camera details.

Headers: Authorization: Bearer {access_token} Required Role: Viewer+

---

Monitors

GET /api/v1/monitors

List all monitors.

Headers: Authorization: Bearer {access_token} Required Role: Viewer+

Response (200 OK):

{
  "monitors": [
    {
      "id": 1,
      "name": "Control Room Monitor 1",
      "description": "Main display",
      "status": "active",
      "current_camera_id": 5
    }
  ],
  "total": 1
}

GET /api/v1/monitors/filter/available

Get available (idle) monitors for cross-switching.

Headers: Authorization: Bearer {access_token} Required Role: Viewer+

---

Cross-Switching (Core Functionality)

POST /api/v1/crossswitch

Execute cross-switch: Route camera to monitor.

Headers: Authorization: Bearer {access_token} Required Role: Operator+ (NOT Viewer)

Request:

{
  "camera_id": 1,
  "monitor_id": 1,
  "mode": 0
}

Response (200 OK):

{
  "success": true,
  "message": "Successfully switched camera 1 to monitor 1",
  "route": {
    "id": "uuid",
    "camera_id": 1,
    "monitor_id": 1,
    "executed_at": "2025-12-09T12:00:00Z",
    "executed_by": "uuid",
    "executed_by_username": "operator",
    "is_active": true
  }
}

POST /api/v1/crossswitch/clear

Clear monitor: Remove camera from monitor.

Headers: Authorization: Bearer {access_token} Required Role: Operator+

Request:

{
  "monitor_id": 1
}

Response (200 OK):

{
  "success": true,
  "message": "Successfully cleared monitor 1",
  "monitor_id": 1
}

GET /api/v1/crossswitch/routing

Get current routing state (active camera-to-monitor mappings).

Headers: Authorization: Bearer {access_token} Required Role: Viewer+

Response (200 OK):

{
  "routes": [
    {
      "id": "uuid",
      "camera_id": 1,
      "monitor_id": 1,
      "executed_at": "2025-12-09T12:00:00Z",
      "executed_by_username": "operator",
      "is_active": true
    }
  ],
  "total": 1
}

GET /api/v1/crossswitch/history

Get routing history with pagination.

Headers: Authorization: Bearer {access_token} Required Role: Viewer+

Query Parameters:

• limit: Max records (1-1000, default: 100)
• offset: Skip records (default: 0)
• camera_id: Filter by camera (optional)
• monitor_id: Filter by monitor (optional)

---

Authorization Roles

Role	Cameras	Monitors	Cross-Switch	Clear Monitor	View Routing
Viewer	✅ Read	✅ Read	❌	❌	✅ Read
Operator	✅ Read	✅ Read	✅ Execute	✅ Execute	✅ Read
Administrator	✅ Read	✅ Read	✅ Execute	✅ Execute	✅ Read

---

Error Responses

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Authentication required"
}

403 Forbidden

{
  "error": "Forbidden",
  "message": "Requires operator role or higher"
}

404 Not Found

{
  "error": "Not Found",
  "detail": "Camera with ID 999 not found"
}

500 Internal Server Error

{
  "error": "Internal Server Error",
  "detail": "Cross-switch operation failed: SDK Bridge connection timeout"
}

---

Rate Limiting

Currently not implemented in MVP. Consider adding in production.

---

Caching

• Cameras: Cached for 60 seconds in Redis
• Monitors: Cached for 60 seconds in Redis
• Routing State: Not cached (real-time from database)

Use use_cache=false query parameter to bypass cache.

---

Audit Logging

All operations are logged to the audit_logs table:

• Authentication attempts (success/failure)
• Cross-switch executions
• Monitor clear operations

Query audit logs via database or add dedicated endpoint in future.