{"openapi":"3.0.0","info":{"title":"Vega Telematics Developer API","version":"4.5.0","description":"# Vega Telematics & Fleet Developer Platform\n\nWelcome to the **Vega Telematics Developer Platform**. Vega provides mission-critical enterprise IoT GPS tracking, fleet management, video telematics, fuel intelligence, remote immobilizer commands, and real-time streaming infrastructure.\n\n---\n\n## 🚀 Quickstart & Architecture Overview\n\nThe Vega Platform offers two complementary API layers depending on your integration architecture:\n\n| API Layer | Base Path | Authentication | Intended Use Case |\n| :--- | :--- | :--- | :--- |\n| **Public Integration API** | `/v1/...` | `api_key` + `organization_name` + `email` query params | ERP, TMS, BRTA/Government compliance, dispatch, billing, and accounting systems. Fast zero-session server-to-server calls. |\n| **Platform REST API** | `/api/...` | `Authorization: Bearer ` header | Full fleet operations, live device tracking, geofence CRUD, alerts, sensor telemetry, video streaming, reports, and administrative management. |\n\n---\n\n## 🌐 Environments & Base URLs\n\nAlways use our production gateway for high availability, automatic load balancing, and unbuffered SSE streaming:\n\n- **Primary API Gateway**: `https://api.vegagps.com` (Recommended for all external integrations)\n- **Direct Platform Host**: `https://track.vegagps.com`\n- **Interactive Developer Portal**: `https://docs.vegagps.com`\n\n---\n\n## 🔐 Authentication Guide\n\n### Method A: Public Integration API Key (for `/v1/*`)\n\nFor external third-party software (e.g. BRTA, Transport Management Systems, SAP/Odoo ERPs), pass your credentials as standard query parameters with every request:\n\n```http\nGET /v1/vehicles/current-location?organization_name=Xeekar&email=dispatcher@xeekar.com&api_key=vg_live_xxxxxxxx&vehicle_id=864540081293581 HTTP/1.1\nHost: api.vegagps.com\n```\n\n- **`api_key`**: Your organization's API Secret Key (obtained from your Platform Admin under *Organization Settings* > *API Keys*).\n- **`organization_name`**: Your company or organization identifier (e.g., `Xeekar`).\n- **`email`**: An active user's email within your organization for audit trail and scope enforcement.\n- **`vehicle_id`**: Target vehicle registration plate, internal vehicle UUID, or device IMEI.\n\n---\n\n### Method B: JWT Bearer Token (for `/api/*`)\n\nFor direct integration with the full platform features:\n\n#### 1. Obtain an Access Token\nSend a POST request to `/auth/login`:\n\n```bash\ncurl -X POST https://api.vegagps.com/auth/login \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"email\": \"user@company.com\",\n \"password\": \"your_secure_password\"\n }'\n```\n\n**Response:**\n```json\n{\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"user\": {\n \"id\": \"c1f7b76e-347f-44de-9e5c-0c153b664d4b\",\n \"name\": \"Operations Team\",\n \"email\": \"user@company.com\",\n \"role\": \"admin\",\n \"org_id\": \"90e544ce-d284-48f0-b8d4-63fcb001a1c5\"\n }\n}\n```\n\n#### 2. Authorize Requests\nPass the returned token in the `Authorization` header of subsequent calls:\n\n```bash\ncurl https://api.vegagps.com/api/devices \\\n -H \"Authorization: Bearer \"\n```\n\n---\n\n## 💡 Practical Integration Recipes\n\n### Recipe 1: Fetch Live Location of a Vehicle (Integration API)\n\n```bash\ncurl \"https://api.vegagps.com/v1/vehicles/current-location?organization_name=Xeekar&email=ops@xeekar.com&api_key=YOUR_API_KEY&vehicle_id=864540081293581\"\n```\n\n```javascript\n// Node.js (Fetch)\nconst params = new URLSearchParams({\n organization_name: 'Xeekar',\n email: 'ops@xeekar.com',\n api_key: 'YOUR_API_KEY',\n vehicle_id: '864540081293581'\n});\n\nconst response = await fetch(`https://api.vegagps.com/v1/vehicles/current-location?${params}`);\nconst data = await response.json();\nconsole.log('Vehicle speed:', data.speed, 'Coordinates:', data.latitude, data.longitude);\n```\n\n```python\n# Python (Requests)\nimport requests\n\nparams = {\n 'organization_name': 'Xeekar',\n 'email': 'ops@xeekar.com',\n 'api_key': 'YOUR_API_KEY',\n 'vehicle_id': '864540081293581'\n}\n\nres = requests.get('https://api.vegagps.com/v1/vehicles/current-location', params=params)\ntelemetry = res.json()\nprint(f\"Lat: {telemetry['latitude']}, Lon: {telemetry['longitude']}, Ignition: {telemetry['ignition']}\")\n```\n\n---\n\n### Recipe 2: Bulk Fleet Status (All Active Vehicles)\n\n```bash\ncurl \"https://api.vegagps.com/v1/vehicles/current-locations?organization_name=Xeekar&email=ops@xeekar.com&api_key=YOUR_API_KEY\"\n```\n\nReturns an array of current locations, speed, ignition status, address, and device connectivity timestamps for every vehicle in your fleet in a single call.\n\n---\n\n### Recipe 3: Real-Time Telemetry Streaming via Server-Sent Events (SSE)\n\nConnect to the live positions event stream without continuous polling:\n\n```javascript\nconst eventSource = new EventSource('https://api.vegagps.com/api/stream/events?token=' + JWT_TOKEN);\n\neventSource.onmessage = (event) => {\n const position = JSON.parse(event.data);\n console.log('Live location update:', position.device_id, position.latitude, position.longitude);\n};\n\neventSource.onerror = (err) => {\n console.error('SSE connection error, will reconnect automatically:', err);\n};\n```\n\n---\n\n### Recipe 4: Remote Engine Cutoff / Mobilizer Command\n\n```bash\ncurl -X POST https://api.${BASE_DOMAIN}/api/commands/send \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"deviceId\": \"c1f7b76e-347f-44de-9e5c-0c153b664d4b\",\n \"commandType\": \"RELAY_STOP\"\n }'\n```\n\n---\n\n### Recipe 5: ERP & Fleet Provisioning Integration (Users, Devices, Assignments & Coin Billing)\n\nFor partners automating client accounts and vehicle onboarding from an internal ERP, CRM, or billing system (e.g. GPSWOX migrations):\n\n#### 1. Device Expiration vs Prepaid Coins Architecture\n- **Single Source of Truth Expiration (`subscription_end`)**: Every vehicle has a single expiration date. When this date passes, the vehicle automatically transitions to expired status.\n- **Prepaid Coins**: Coins represent your organization's prepaid tracking credits with Vega:\n - **Adding a device** automatically debits **1 Coin** and provisions **12 months (365 days)** of validity.\n - **Renewing a device** debits **1 Coin** and extends validity by another **12 months**.\n - **Client User Accounts**: Do not expire per-device; manage client access by activating or suspending user accounts.\n\n#### 2. Workflow: Onboard Customer, Register Device & Link Access\n\n##### Step A: Create Client User\n```bash\ncurl -X POST https://api.${BASE_DOMAIN}/api/users \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Acme Logistics\",\n \"email\": \"ops@acmelogistics.com\",\n \"phone\": \"+8801700000000\",\n \"password\": \"TempPassword123\",\n \"role_id\": \"1059166a-54ee-4ced-aa7e-c36053f59a24\"\n }'\n```\n*(Returns user UUID: `{\"success\": true, \"data\": {\"id\": \"c1f7b76e-...\"}}`)*\n\n##### Step B: Provision Hardware Device (Auto-debits 1 coin, sets 1-year validity)\n```bash\ncurl -X POST https://api.${BASE_DOMAIN}/api/devices \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"imei\": \"864540081293581\",\n \"name\": \"Toyota Premio - DHK-METRO-GA-11-2041\",\n \"plate_number\": \"DHK-METRO-GA-11-2041\",\n \"sim_number\": \"+8801812345678\",\n \"model\": \"Concox GT06\",\n \"user_ids\": [\"c1f7b76e-347f-44de-9e5c-0c153b664d4b\"]\n }'\n```\n\n##### Step C: Renew Device Subscription (Extends by 12 months)\n```bash\ncurl -X POST https://api.${BASE_DOMAIN}/api/devices/864540081293581/renew \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"coins\": 1\n }'\n```\n\n##### Step D: Assign or Replace Users on Device\n```bash\ncurl -X PUT https://api.${BASE_DOMAIN}/api/devices/864540081293581/assigned-users \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"user_ids\": [\"c1f7b76e-347f-44de-9e5c-0c153b664d4b\"]\n }'\n```\n\n##### Step E: Suspend or Reactivate Client Account (ERP Billing Hook)\n```bash\ncurl -X PATCH https://api.${BASE_DOMAIN}/api/users/c1f7b76e-347f-44de-9e5c-0c153b664d4b/status \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"active\": false\n }'\n```\n\n##### Step F: Check Organization Coin Balance\n```bash\ncurl https://api.${BASE_DOMAIN}/api/billing/balance \\\n -H \"Authorization: Bearer \"\n```\n\n---\n\n## 📊 Standard HTTP Response Codes\n\n| Status Code | Description | Typical Cause / Resolution |\n| :--- | :--- | :--- |\n| **`200 OK`** | Request succeeded | Target data returned in response body. |\n| **`201 Created`** | Resource created | Device, geofence, or user was successfully provisioned. |\n| **`400 Bad Request`** | Validation error | Missing required parameters (`api_key`, `organization_name`, etc.) or invalid JSON payload. |\n| **`401 Unauthorized`** | Authentication failed | Missing, expired, or invalid API key or JWT token. |\n| **`403 Forbidden`** | Access denied | User or key does not have permission to access the requested organization or vehicle. |\n| **`404 Not Found`** | Resource not found | Vehicle, device ID, or endpoint URL does not exist. |\n| **`429 Too Many Requests`** | Rate limit exceeded | Back off and retry. Default limit is 1,000 requests per 15 minutes. |\n| **`500 Internal Error`** | Server error | An unexpected server error occurred. Contact support with the `x-request-id` header. |\n","contact":{"name":"Vega Telematics Developer Support","url":"https://vegagps.com"}},"servers":[{"url":"https://api.vegagps.com","description":"Production API Gateway (Recommended)"},{"url":"https://track.vegagps.com","description":"Tracking Platform Direct"},{"url":"https://docs.vegagps.com","description":"Documentation Proxy"}],"tags":[{"name":"Public Integration API","description":"V1 public integration endpoints (API Key authentication) for ERP, TMS, and Government systems"},{"name":"Authentication","description":"User authentication, registration, access requests, password resets, and session management"},{"name":"Health","description":"Service health checks and cron heartbeats"},{"name":"Devices","description":"Device CRUD, fleet assignment, subscriptions"},{"name":"Positions","description":"GPS position history queries"},{"name":"Streams","description":"Server-Sent Events (SSE) for live tracking positions, alerts, and system status"},{"name":"Fleets","description":"Fleet/group management"},{"name":"Drivers","description":"Driver management and vehicle assignment"},{"name":"Trailers","description":"Trailers and asset hitching/unhitching management"},{"name":"Favorites","description":"Favorite/pinned device management"},{"name":"Alerts","description":"Alert rules, history, and templates"},{"name":"Geofences","description":"Geofence CRUD (circle/polygon)"},{"name":"Notification Profiles","description":"Notification group profiles"},{"name":"Notification Templates","description":"Notification email, SMS, push, and webhook templates"},{"name":"Notifications","description":"In-app notifications and alert inbox"},{"name":"Reports","description":"Report generation, storage, and scheduling"},{"name":"Analytics","description":"Dashboard analytics and KPIs"},{"name":"Trip Engine","description":"Enterprise commercial trip dispatch, leg scoring, fuel curves, and cargo accounting"},{"name":"Bulk Fuel Tanks","description":"Yard stationary fuel storage tanks, intake logs, and vehicle dispensations"},{"name":"Stats","description":"Fleet statistics"},{"name":"Video Telematics","description":"JT/T 1078 live video streaming, playback, PTZ control, and health monitoring"},{"name":"Uploads & Media","description":"Jimi IoT dashcam media uploads, video recordings, and alarm attachments"},{"name":"Sensors","description":"Sensor templates and device sensor configuration"},{"name":"Commands","description":"GPRS command interface (engine cutoff, etc.)"},{"name":"Maintenance","description":"Service intervals and maintenance logs"},{"name":"Inspections","description":"Vehicle inspection checklists and defect reporting"},{"name":"Expenses","description":"Fleet expense tracking, fuel logs, and cost summaries"},{"name":"Tasks","description":"Task/job dispatch"},{"name":"Routes","description":"Route planning and management"},{"name":"POI","description":"Points of Interest library"},{"name":"Trip Notes","description":"Trip annotations and operational notes"},{"name":"Bulk Operations","description":"Bulk device operations (import, delete, assign)"},{"name":"Share","description":"Public tracking link sharing"},{"name":"Chat","description":"Driver-dispatcher and platform in-app messaging"},{"name":"AI Assistant","description":"AI-powered natural language fleet queries and intelligent insights"},{"name":"Search","description":"Unified global search across devices, drivers, fleets, and geofences"},{"name":"Fuel Prices","description":"Live fuel price discovery and nearest station locator"},{"name":"Weather","description":"Live weather conditions for device coordinates"},{"name":"Certificates","description":"GPS tracker installation and compliance certificates"},{"name":"Users","description":"User management (admin only)"},{"name":"Organizations","description":"Organization settings and billing"},{"name":"Roles","description":"Custom roles and permissions"},{"name":"Custom Fields","description":"Dynamic custom entity fields and schemas"},{"name":"Domains","description":"Custom domain management and SSL/TLS verification"},{"name":"Branding","description":"White-label branding configuration"},{"name":"Billing","description":"Coin-based billing and balance transactions"},{"name":"Payments","description":"Subscription plans and payment gateway integration"},{"name":"Security","description":"Security dashboard, session controls, and access logs"},{"name":"IP Management","description":"Rate limit and IP blacklist management"},{"name":"Admin Diagnostics","description":"Raw binary packet inspection and system performance metrics"},{"name":"Settings","description":"System settings (device timeout, speed thresholds)"},{"name":"Unknown Devices","description":"Device onboarding / pending approval"},{"name":"Simulator","description":"GPS device simulator control"},{"name":"Telemetry","description":"Mobile app crash logs and performance telemetry"}],"paths":{"/health":{"get":{"description":"Retrieves a paginated list of Health accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Health"],"parameters":[],"summary":"Get Health"}},"/health/crons":{"get":{"description":"Retrieves a paginated list of Health Crons accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Health"],"summary":"Get Health Crons"}},"/health/reconnects":{"get":{"description":"Retrieves a paginated list of Health Reconnects accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Health"],"summary":"Get Health Reconnects"}},"/internal/metrics":{"get":{"description":"Retrieves a paginated list of Internal Metrics accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Health"],"summary":"Get Internal Metrics"}},"/internal/device-exists/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Internal Device-exists Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"}],"responses":{"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Health"],"summary":"Get Internal Device-exists Imei"}},"/api/internal/verify-domain":{"get":{"description":"Retrieves a paginated list of Internal Verify-domain accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"domain","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Domains"],"summary":"Get Internal Verify-domain"}},"/upload":{"post":{"description":"Provisions, dispatches, or creates a new Upload in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imei":{"example":"any"},"filename":{"example":"any"},"fileName":{"example":"any"},"timestamp":{"example":"any"},"sign":{"example":"any"},"callbackBody":{"example":"any"},"fileType":{"example":"any"}}}}}},"tags":["Uploads & Media"],"summary":"Create or Trigger Upload"}},"/api/upload":{"post":{"description":"Provisions, dispatches, or creates a new Upload in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imei":{"example":"any"},"filename":{"example":"any"},"fileName":{"example":"any"},"timestamp":{"example":"any"},"sign":{"example":"any"},"callbackBody":{"example":"any"},"fileType":{"example":"any"}}}}}},"tags":["Uploads & Media"],"summary":"Create or Trigger Upload"}},"/api/internal/jimi/upload":{"post":{"description":"Provisions, dispatches, or creates a new Internal Jimi Upload in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imei":{"example":"any"},"filename":{"example":"any"},"fileName":{"example":"any"},"timestamp":{"example":"any"},"sign":{"example":"any"},"callbackBody":{"example":"any"},"fileType":{"example":"any"}}}}}},"tags":["Uploads & Media"],"summary":"Create or Trigger Internal Jimi Upload"}},"/api/admin/packets/devices":{"get":{"description":"Retrieves a paginated list of Admin Packets Devices accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Admin Diagnostics"],"summary":"Get Admin Packets Devices"}},"/api/admin/devices/{imei}/packets":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Admin Devices Imei Packets within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Admin Devices Imei Packets"}},"/api/internal/media/on_publish":{"post":{"description":"Provisions, dispatches, or creates a new Internal Media On_publish in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"stream":{"example":"any"},"type":{"example":"any"},"session":{"example":"any"}}}}}},"tags":["Video Telematics"],"summary":"Create or Trigger Internal Media On_publish"}},"/api/internal/media/on_publish_done":{"post":{"description":"Provisions, dispatches, or creates a new Internal Media On_publish_done in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"stream":{"example":"any"},"type":{"example":"any"},"session":{"example":"any"}}}}}},"tags":["Video Telematics"],"summary":"Create or Trigger Internal Media On_publish_done"}},"/api/internal/media/on_idle_timeout":{"post":{"description":"Provisions, dispatches, or creates a new Internal Media On_idle_timeout in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"stream":{"example":"any"},"type":{"example":"any"},"session":{"example":"any"}}}}}},"tags":["Video Telematics"],"summary":"Create or Trigger Internal Media On_idle_timeout"}},"/api/branding":{"get":{"description":"Retrieves white-label logo URL, favicon, page title, company support email, and primary accent theme color.","parameters":[{"name":"domain","in":"query","schema":{"type":"string"}},{"name":"slug","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Branding configuration."},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Branding"],"summary":"Get White-Label Custom Branding Assets & Theme","security":[{"bearerAuth":[]}]}},"/api/branding/mobile/{slug}":{"get":{"description":"Retrieves a paginated list of Branding Mobile Slug accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"tags":["Branding"],"summary":"Get Branding Mobile Slug"}},"/api/metadata":{"get":{"description":"Retrieves a paginated list of Metadata accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"domain","in":"query","schema":{"type":"string"}},{"name":"slug","in":"query","schema":{"type":"string"}},{"name":"path","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Branding"],"summary":"Get Metadata"}},"/api/metadata/manifest":{"get":{"description":"Retrieves a paginated list of Metadata Manifest accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","produces":["application/manifest+json"],"parameters":[{"name":"domain","in":"query","schema":{"type":"string"}},{"name":"slug","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Branding"],"summary":"Get Metadata Manifest"}},"/api/share/verify-certificate/{certNo}":{"get":{"description":"Retrieves a paginated list of Share Verify-certificate CertNo accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"certNo","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"tags":["Share"],"summary":"Get Share Verify-certificate CertNo"}},"/api/share/{token}":{"get":{"description":"Retrieves a paginated list of Share Token accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"tags":["Share"],"summary":"Get Share Token"}},"/api/share":{"get":{"description":"Retrieves a paginated list of Share accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Share"],"summary":"Get Share"},"post":{"description":"Provisions, dispatches, or creates a new Share in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resource_type":{"example":"any"},"resource_id":{"example":"any"},"duration_hours":{"example":"any"},"duration_days":{"example":"any"}}}}}},"tags":["Share"],"summary":"Create or Trigger Share"}},"/api/share/{id}":{"delete":{"description":"Permanently removes or unlinks the target Share Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Share"],"summary":"Delete Share Id"}},"/api/telemetry/mobile":{"post":{"description":"Provisions, dispatches, or creates a new Telemetry Mobile in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"events":{"example":"any"}}}}}},"tags":["Telemetry"],"summary":"Create or Trigger Telemetry Mobile"}},"/api/v1/telemetry/ingest/pilot":{"post":{"description":"Provisions, dispatches, or creates a new Telemetry Ingest Pilot in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"summary":"Create or Trigger Telemetry Ingest Pilot"}},"/v1/vehicles/current-location":{"get":{"description":"Retrieves real-time GPS coordinates, speed, heading, ignition state, and last reported timestamp for a single vehicle.\n\n### Use Case\nIdeal for single-vehicle tracking widgets, customer dispatch tracking portals, BRTA government compliance pushes, or ERP systems updating active vehicle coordinates.\n\n### Authentication\nRequires `organization_name`, `email`, and `api_key` passed as query parameters.\n\n### Vehicle Identifier\nYou can supply either the device **IMEI** (e.g. `864540081293581`), the vehicle **registration plate** (e.g. `DHK-METRO-GA-11-2041`), or internal **vehicle_id**.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"organization_name","in":"query","schema":{"type":"string","example":"Xeekar"},"required":true,"description":"Organization name or slug (e.g. Xeekar)"},{"name":"vehicle_id","in":"query","schema":{"type":"string","example":"864540081293581"},"required":true,"description":"Target vehicle identifier: device IMEI, license plate number, or vehicle UUID"},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email address for authorization and audit trail"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API secret key (from Organization Settings > API Keys)"}],"responses":{"200":{"description":"Real-time vehicle location and telemetry data.","content":{"application/json":{"example":{"success":true,"message":"Vehicle location fetched successfully.","data":[{"vehicle_id":"864540081293581","vehicle_name":"Toyota Allion 2024","registration_number":"DHK-METRO-GA-11-2041","vehicle_type":"Car","ignition_status":"ON","speed":48,"heading":184,"timestamp":"2026-10-01T10:15:30.000Z","location":{"latitude":23.810332,"longitude":90.412518}}]}}}},"400":{"description":"Missing required query parameters.","content":{"application/json":{"example":{"success":false,"message":"Missing required query parameters: organization_name (or organization_id), email, and api_key are required."}}}},"401":{"description":"Invalid or expired API key, unknown organization, or inactive user email."},"403":{"description":"Forbidden"},"404":{"description":"Vehicle not found within this organization."},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get Live Location & Telemetry for a Specific Vehicle"}},"/v1/vehicles/current-locations":{"get":{"description":"Retrieves current coordinates, speed, heading, and ignition status for every active vehicle in your fleet in a single high-performance API call.\n\n### Use Case\nIdeal for dispatch centers, central monitoring screens, GIS integrations, and third-party TMS synchronizing whole-fleet positions every 10–30 seconds.\n\n### Filtering Options\nYou can optionally filter by `status` (`moving`, `idle`, `stopped`, `offline`) or by `fleet_id`.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"organization_name","in":"query","schema":{"type":"string","example":"Xeekar"},"required":true,"description":"Organization name or slug (e.g. Xeekar)"},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email address"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API secret key"},{"name":"fleet_id","in":"query","schema":{"type":"string","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b"},"required":false,"description":"Filter vehicles by specific fleet group ID"},{"name":"status","in":"query","schema":{"type":"string","example":"moving","enum":["moving","idle","stopped","offline"]},"required":false,"description":"Filter by current vehicle operational motion status"}],"responses":{"200":{"description":"Bulk array of current vehicle locations and fleet count.","content":{"application/json":{"example":{"success":true,"message":"Vehicle locations fetched successfully.","vehicle_count":2,"data":[{"vehicle_id":"864540081293581","vehicle_name":"Toyota Allion 2024","registration_number":"DHK-METRO-GA-11-2041","vehicle_type":"Car","ignition_status":"ON","speed":55,"heading":192,"timestamp":"2026-10-01T10:15:30.000Z","location":{"latitude":23.810332,"longitude":90.412518}},{"vehicle_id":"865167047241865","vehicle_name":"Hino 500 Heavy Truck","registration_number":"RAJ-BA-11-0079","vehicle_type":"Truck","ignition_status":"OFF","speed":0,"heading":45,"timestamp":"2026-10-01T10:14:15.000Z","location":{"latitude":24.363588,"longitude":88.624135}}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get Bulk Live Locations for All Active Fleet Vehicles"}},"/v1/fleet/status":{"get":{"description":"Returns aggregate counts of fleet vehicles categorized by motion state: moving, idling, parked/stopped, and offline.\n\n### Use Case\nExecutive dashboards, KPI widgets, and high-level health monitors that need quick numerical status without downloading coordinates.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API key"},{"name":"organization_name","in":"query","required":true,"description":"Organization name or slug","schema":{"type":"string","example":"Xeekar"}}],"responses":{"200":{"description":"High-level fleet summary counts.","content":{"application/json":{"example":{"success":true,"data":{"total_vehicles":120,"moving":48,"idle":14,"stopped":52,"offline":6}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get High-Level Fleet Operational Status & Breakdown Counts"}},"/v1/vehicles/registry":{"get":{"description":"Returns the full catalog of enrolled vehicles in the organization, including vehicle model, registration plates, installed tracker hardware IMEI, and device model.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API key"},{"name":"organization_name","in":"query","required":true,"description":"Organization name or slug","schema":{"type":"string","example":"Xeekar"}}],"responses":{"200":{"description":"List of registered fleet vehicles.","content":{"application/json":{"example":{"success":true,"data":[{"vehicle_id":"864540081293581","registration_number":"DHK-METRO-GA-11-2041","vehicle_name":"Toyota Allion 2024","vehicle_type":"Car","device_model":"GT06Pro","speed_limit_kmh":80}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get Complete Vehicle Registry & Hardware Inventory"}},"/v1/vehicles/trip-history":{"get":{"description":"Returns historical timestamped GPS points, speed, and heading over a specified time window.\n\n### Use Case\nRoute playback recreation, driver route compliance audits, and route corridor verification.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API key"},{"name":"vehicle_id","in":"query","schema":{"type":"string","example":"864540081293581"},"required":true,"description":"Vehicle IMEI or license plate number"},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"organization_name","in":"query","required":true,"description":"Organization name or slug","schema":{"type":"string","example":"Xeekar"}},{"name":"from","in":"query","required":true,"description":"Start timestamp (ISO-8601 UTC)","schema":{"type":"string","example":"2026-10-01T00:00:00Z"}},{"name":"to","in":"query","required":true,"description":"End timestamp (ISO-8601 UTC)","schema":{"type":"string","example":"2026-10-01T23:59:59Z"}}],"responses":{"200":{"description":"Chronological GPS track waypoints.","content":{"application/json":{"example":{"success":true,"vehicle_id":"864540081293581","points_count":240,"data":[{"timestamp":"2026-10-01T08:00:10Z","latitude":23.8103,"longitude":90.4125,"speed":42,"heading":180,"ignition":true}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get Historical Waypoint Trajectory & Trip Track for a Vehicle"}},"/v1/vehicles/daily-distance":{"get":{"description":"Calculates total distance traveled in kilometers, engine operating hours, and idle duration grouped by vehicle and day.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API key"},{"name":"vehicle_id","in":"query","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"organization_name","in":"query","required":true,"description":"Organization name or slug","schema":{"type":"string","example":"Xeekar"}},{"name":"date","in":"query","required":false,"description":"Target date (YYYY-MM-DD). Defaults to today.","schema":{"type":"string","example":"2026-10-01"}}],"responses":{"200":{"description":"Daily mileage summary per vehicle.","content":{"application/json":{"example":{"success":true,"date":"2026-10-01","data":[{"vehicle_id":"864540081293581","registration_number":"DHK-METRO-GA-11-2041","distance_km":148.6,"engine_hours":4.8,"idle_hours":0.9,"max_speed":78}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get Daily Distance Driven & Mileage Report"}},"/v1/vehicles/stop-report":{"get":{"description":"Lists all vehicle stops, parking locations, stop durations, and arrival/departure timestamps.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API key"},{"name":"vehicle_id","in":"query","schema":{"type":"string","example":"864540081293581"},"required":true,"description":"Vehicle identifier"},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"organization_name","in":"query","required":true,"description":"Organization name or slug","schema":{"type":"string","example":"Xeekar"}}],"responses":{"200":{"description":"List of recorded vehicle stops.","content":{"application/json":{"example":{"success":true,"data":[{"stopped_at":"2026-10-01T09:12:00Z","departed_at":"2026-10-01T09:45:00Z","duration_minutes":33,"latitude":23.8211,"longitude":90.4285,"location_name":"Uttara Sector 7 Depot, Dhaka"}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get Vehicle Parking & Stop Report"}},"/v1/vehicles/overspeed-violations":{"get":{"description":"Returns overspeed violations where a vehicle exceeded its configured maximum speed threshold.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API key"},{"name":"vehicle_id","in":"query","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"organization_name","in":"query","required":true,"description":"Organization name or slug","schema":{"type":"string","example":"Xeekar"}}],"responses":{"200":{"description":"List of recorded overspeed incidents.","content":{"application/json":{"example":{"success":true,"data":[{"vehicle_id":"864540081293581","registration_number":"DHK-METRO-GA-11-2041","speed":92,"speed_limit":80,"timestamp":"2026-10-01T09:30:15Z","latitude":23.834,"longitude":90.419}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get Overspeed Event Logs & Violations"}},"/api/stream/positions":{"get":{"description":"Opens a persistent, unbuffered Server-Sent Events (SSE) connection that streams real-time GPS coordinates, speed, heading, and ignition states for all devices in the authenticated organization.\n \n### Connection Details\n- Streams both fast raw gateway pings and enriched worker telemetry (fuel level, battery, temperature).\n- Keeps the connection alive with automatic 15-second heartbeat comments (`: ping`).\n- Accepts Bearer token via `Authorization` header or `?token=` query parameter (compatible with native browser `EventSource`).","parameters":[{"name":"imeis","in":"query","schema":{"type":"string"}},{"name":"token","in":"query","schema":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"required":false,"description":"JWT Bearer token (for browser EventSource which cannot set custom HTTP headers)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Text/event-stream real-time telemetry stream.","content":{"text/event-stream":{"schema":{"type":"string"},"example":"data: {\"imei\":\"864540081293581\",\"lat\":23.8103,\"lon\":90.4125,\"speed\":48,\"ignition\":true,\"time\":\"2026-10-01T10:20:15Z\"}\n\n"}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"429":{"description":"Too Many Requests"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Streams"],"summary":"Live Fleet Positions Stream (Server-Sent Events / SSE)","security":[{"bearerAuth":[]}]}},"/api/stream/positions/{imei}":{"get":{"description":"Streams high-frequency real-time updates for an individual vehicle. Ideal for active turn-by-turn map views, vehicle chase mode, or live dashboard gauges.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit target device IMEI"},{"name":"token","in":"query","schema":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"description":"JWT Bearer token for EventSource authentication"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Continuous SSE stream of telemetry points for the single device.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"429":{"description":"Too Many Requests"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Streams"],"summary":"Single Device Live Telemetry Stream (SSE)","security":[{"bearerAuth":[]}]}},"/api/stream/alerts":{"get":{"description":"Pushes instant notifications whenever a rule is triggered across the fleet (overspeed, geofence enter/exit, SOS panic button, towing detection, power disconnection, or harsh driving).","parameters":[{"name":"token","in":"query","schema":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"description":"JWT Bearer token for EventSource authentication"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Stream of real-time alert events.","content":{"text/event-stream":{"schema":{"type":"string"},"example":"data: {\"id\":\"a8b3...\",\"type\":\"overspeed\",\"vehicle_name\":\"Toyota Allion\",\"speed\":92,\"speed_limit\":80,\"timestamp\":\"2026-10-01T10:21:00Z\"}\n\n"}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"429":{"description":"Too Many Requests"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Streams"],"summary":"Live Fleet Alert Events Stream (SSE)","security":[{"bearerAuth":[]}]}},"/api/stream/chat/{roomId}":{"get":{"description":"Streams instant messages between dispatchers, fleet operators, and assigned drivers inside a specific conversation room.","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string","example":"room-14-dispatch"},"description":"Chat conversation room UUID or identifier"},{"name":"token","in":"query","schema":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"description":"JWT Bearer token for EventSource authentication"}],"responses":{"200":{"description":"Chat messages text/event-stream.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"429":{"description":"Too Many Requests"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Streams"],"summary":"Real-Time Dispatch Chat Stream (SSE)","security":[{"bearerAuth":[]}]}},"/api/stream/status":{"get":{"description":"Provides real-time health statistics of the streaming cluster, including number of active client connections and Redis subscriber status.","parameters":[],"responses":{"200":{"description":"Active streaming connection metrics.","content":{"application/json":{"example":{"activeConnections":18,"maxAllowedPerUser":25,"redisChannels":["vega:live","vega:stream","vega:alert"],"timestamp":"2026-10-01T10:22:00Z"}}}},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Streams"],"summary":"Get SSE Streaming Server Health & Connection Metrics","security":[{"bearerAuth":[]}]}},"/api/users/me/profile":{"get":{"description":"Returns current user account details, assigned roles, organization UUID, avatar URL, and effective RBAC permissions bitmask.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Current user profile.","content":{"application/json":{"example":{"success":true,"data":{"id":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","name":"Fleet Manager","email":"dispatcher@xeekar.com","role":"admin","org_id":"90e544ce-d284-48f0-b8d4-63fcb001a1c5","timezone":"Asia/Dhaka","isPlatformAdmin":false}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Authenticated User Profile & Active Permissions","security":[{"bearerAuth":[]}]},"put":{"description":"Allows authenticated user to update their display name, phone number, or avatar.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Profile updated."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Fleet Operations Manager"},"phone":{"type":"string","example":"+8801712345678"}}},"example":{"name":"Fleet Operations Manager","phone":"+8801712345678"}}}},"tags":["Users"],"summary":"Update Personal Profile Details","security":[{"bearerAuth":[]}]}},"/api/users/me/timezone":{"put":{"description":"Updates and overwrites properties of the target Users Me Timezone.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"timezone":{"example":"any"}}}}}},"tags":["Users"],"summary":"Update Users Me Timezone"}},"/api/users/me/preferences":{"get":{"description":"Retrieves a paginated list of Users Me Preferences accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Users Me Preferences"},"put":{"description":"Updates and overwrites properties of the target Users Me Preferences.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Update Users Me Preferences"}},"/api/users/me/notification-preferences":{"get":{"description":"Retrieves a paginated list of Users Me Notification-preferences accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Users Me Notification-preferences"},"put":{"description":"Updates and overwrites properties of the target Users Me Notification-preferences.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"example":"any"},"sound_enabled":{"example":"any"},"sound_mode":{"example":"any"},"desktop_enabled":{"example":"any"},"push_enabled":{"example":"any"},"volume":{"example":"any"},"muted_rule_ids":{"example":"any"},"muted_device_alerts":{"example":"any"},"dnd_enabled":{"example":"any"},"dnd_start":{"example":"any"},"dnd_end":{"example":"any"},"dnd_timezone":{"example":"any"},"admin_fleet_scope":{"example":"any"},"fleet_routine_alerts":{"example":"any"}}}}}},"tags":["Users"],"summary":"Update Users Me Notification-preferences"}},"/api/users/me/sessions":{"get":{"description":"Retrieves a paginated list of Users Me Sessions accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Users Me Sessions"},"delete":{"description":"Permanently removes or unlinks the target Users Me Sessions from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Delete Users Me Sessions"}},"/api/users/me/account":{"delete":{"description":"Permanently removes or unlinks the target Users Me Account from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Delete Users Me Account"}},"/api/users/fcm-token":{"post":{"description":"Registers or updates the mobile device or web browser push notification token to receive real-time alerts.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"FCM push token registered."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Firebase device push registration token","example":"f87a9bc2...43f"},"platform":{"type":"string","enum":["android","ios","web"],"example":"android"}}},"example":{"token":"f87a9bc2...43f","platform":"android"}}}},"tags":["Users"],"summary":"Register Firebase Cloud Messaging (FCM) Push Token","security":[{"bearerAuth":[]}]},"delete":{"description":"Permanently removes or unlinks the target Users Fcm-token from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"example":"any"}}}}}},"tags":["Users"],"summary":"Delete Users Fcm-token"}},"/api/users":{"get":{"description":"Retrieves all users enrolled in the tenant organization, their roles, active status, and last login timestamps.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of users."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"List Organization Users & Sub-Accounts","security":[{"bearerAuth":[]}]},"post":{"description":"Provisions a new user account under the organization and sends activation credentials.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"User created successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password","name"],"properties":{"email":{"type":"string","format":"email","example":"ops2@company.com"},"password":{"type":"string","minLength":4,"maxLength":10,"description":"User password (4 to 10 characters)","example":"Temp1234"},"name":{"type":"string","example":"Assistant Dispatcher"},"role":{"type":"string","enum":["admin","manager","viewer","driver","dispatcher"],"description":"Friendly role name (auto-mapped to tenant role ID)","example":"manager"},"role_id":{"type":"string","format":"uuid","description":"Tenant role UUID (provide either role or role_id)","example":"1059166a-54ee-4ced-aa7e-c36053f59a24"},"phone":{"type":"string","example":"+8801712345678"}}},"example":{"email":"ops2@company.com","password":"Temp1234","name":"Assistant Dispatcher","role":"manager"}}}},"tags":["Users"],"summary":"Create / Invite New User","security":[{"bearerAuth":[]}]}},"/api/users/bulk-import":{"post":{"description":"Provisions, dispatches, or creates a new Users Bulk-import in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"users":{"example":"any"}}}}}},"tags":["Users"],"summary":"Create or Trigger Users Bulk-import"}},"/api/users/{id}":{"put":{"description":"Updates an existing user account under the organization, including display name, contact phone, email, assigned role, or active status.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","format":"uuid"},"description":"Unique UUID of the user account"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"User updated successfully.","content":{"application/json":{"example":{"success":true,"message":"User updated successfully"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Customer Support Lead"},"email":{"type":"string","format":"email","example":"lead@company.com"},"phone":{"type":"string","example":"+8801700000000"},"role":{"type":"string","enum":["admin","manager","viewer","driver","dispatcher"],"description":"Friendly role name","example":"manager"},"role_id":{"type":"string","format":"uuid","example":"1059166a-54ee-4ced-aa7e-c36053f59a24"},"password":{"type":"string","minLength":4,"maxLength":10,"description":"New password (4 to 10 characters)","example":"NewPass1"},"active":{"type":"boolean","example":true}}},"example":{"name":"Customer Support Lead","phone":"+8801700000000","active":true}}}},"tags":["Users"],"summary":"Update User Profile, Role, or Status","security":[{"bearerAuth":[]}]},"delete":{"description":"Permanently removes a user account from the organization and revokes all vehicle assignments and active sessions.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","format":"uuid"},"description":"Unique UUID of the user account to delete"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"User deleted successfully.","content":{"application/json":{"example":{"success":true,"message":"User deleted successfully"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Delete User Account","security":[{"bearerAuth":[]}]}},"/api/users/{id}/status":{"patch":{"description":"Toggles a user between active and suspended states. Suspended users cannot log in or receive notifications. Ideal for automated ERP billing suspension.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","format":"uuid"},"description":"Unique UUID of the user account"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"User status updated successfully.","content":{"application/json":{"example":{"success":true,"data":{"id":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","email":"customer@example.com","name":"Customer Name","active":false}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["active"],"properties":{"active":{"type":"boolean","description":"true to activate, false to suspend","example":false}}},"example":{"active":false}}}},"tags":["Users"],"summary":"Activate or Suspend User Account","security":[{"bearerAuth":[]}]}},"/api/users/{id}/reveal-password":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Users Id Reveal-password within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Users Id Reveal-password"}},"/api/users/{id}/set-password":{"post":{"description":"Overrides and resets a user password directly without requiring the old password. Designed for ERP/Admin onboarding.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","format":"uuid"},"description":"Unique UUID of the user account"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Password updated successfully.","content":{"application/json":{"example":{"success":true,"message":"Password updated successfully"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["password"],"properties":{"password":{"type":"string","minLength":4,"maxLength":10,"example":"Pass1234"}}},"example":{"password":"Pass1234"}}}},"tags":["Users"],"summary":"Admin Set User Password","security":[{"bearerAuth":[]}]}},"/api/users/{id}/fleet-assignments":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Users Id Fleet-assignments within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Users Id Fleet-assignments"},"put":{"description":"Updates and overwrites properties of the target Users Id Fleet-assignments.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fleet_ids":{"example":"any"}}}}}},"tags":["Users"],"summary":"Update Users Id Fleet-assignments"}},"/api/users/{id}/device-assignments":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Users Id Device-assignments within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Users Id Device-assignments"},"put":{"description":"Updates and overwrites properties of the target Users Id Device-assignments.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_imeis":{"example":"any"}}}}}},"tags":["Users"],"summary":"Update Users Id Device-assignments"},"post":{"description":"Provisions, dispatches, or creates a new Users Id Device-assignments in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_imeis":{"example":"any"}}}}}},"tags":["Users"],"summary":"Create or Trigger Users Id Device-assignments"},"delete":{"description":"Permanently removes or unlinks the target Users Id Device-assignments from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_imeis":{"example":"any"}}}}}},"tags":["Users"],"summary":"Delete Users Id Device-assignments"}},"/api/users/me/device-assignments":{"get":{"description":"Retrieves a paginated list of Users Me Device-assignments accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Users Me Device-assignments"},"put":{"description":"Updates and overwrites properties of the target Users Me Device-assignments.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_imeis":{"example":"any"}}}}}},"tags":["Users"],"summary":"Update Users Me Device-assignments"}},"/api/users/{id}/impersonate":{"post":{"description":"Provisions, dispatches, or creates a new Users Id Impersonate in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Create or Trigger Users Id Impersonate"}},"/api/org/hub/destinations":{"get":{"description":"Retrieves a paginated list of Org Hub Destinations accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Hub Destinations"},"post":{"description":"Provisions, dispatches, or creates a new Org Hub Destinations in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"active":{"example":"any"},"url":{"example":"any"},"authHeader":{"example":"any"},"format":{"example":"any"},"batchSize":{"example":"any"},"flushIntervalMs":{"example":"any"},"vendorConfig":{"example":"any"},"brokerUrl":{"example":"any"},"topic":{"example":"any"},"username":{"example":"any"},"password":{"example":"any"},"host":{"example":"any"},"port":{"example":"any"},"device_scope":{"example":"any"},"device_imeis":{"example":"any"},"user_id":{"example":"any"},"user_ids":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Create or Trigger Org Hub Destinations"}},"/api/org/hub/providers":{"get":{"description":"Retrieves a paginated list of Org Hub Providers accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Hub Providers"}},"/api/org/hub/providers/{providerKey}":{"put":{"description":"Updates and overwrites properties of the target Org Hub Providers ProviderKey.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"providerKey","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"endpoint_url":{"example":"any"},"auth_type":{"example":"any"},"config":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Hub Providers ProviderKey"}},"/api/org/hub/destinations/{id}":{"put":{"description":"Updates and overwrites properties of the target Org Hub Destinations Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"active":{"example":"any"},"url":{"example":"any"},"authHeader":{"example":"any"},"format":{"example":"any"},"batchSize":{"example":"any"},"flushIntervalMs":{"example":"any"},"vendorConfig":{"example":"any"},"brokerUrl":{"example":"any"},"topic":{"example":"any"},"username":{"example":"any"},"password":{"example":"any"},"host":{"example":"any"},"port":{"example":"any"},"device_scope":{"example":"any"},"device_imeis":{"example":"any"},"user_id":{"example":"any"},"user_ids":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Hub Destinations Id"},"delete":{"description":"Permanently removes or unlinks the target Org Hub Destinations Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Delete Org Hub Destinations Id"}},"/api/org/hub/destinations/{id}/devices":{"put":{"description":"Updates and overwrites properties of the target Org Hub Destinations Id Devices.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_scope":{"example":"any"},"device_imeis":{"example":"any"},"user_id":{"example":"any"},"user_ids":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Hub Destinations Id Devices"}},"/api/org/hub/destinations/{id}/test":{"post":{"description":"Provisions, dispatches, or creates a new Org Hub Destinations Id Test in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imei":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Create or Trigger Org Hub Destinations Id Test"}},"/api/org/hub/toggle-mode":{"put":{"description":"Updates and overwrites properties of the target Org Hub Toggle-mode.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"storage_enabled":{"example":"any"},"forwarding_enabled":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Hub Toggle-mode"}},"/api/org/hub/scope":{"put":{"description":"Updates and overwrites properties of the target Org Hub Scope.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"example":"any"},"org_wide":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Hub Scope"}},"/api/org/hub/devices":{"get":{"description":"Retrieves a paginated list of Org Hub Devices accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Hub Devices"},"put":{"description":"Updates and overwrites properties of the target Org Hub Devices.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Hub Devices"}},"/api/org/hub/destinations/{id}/logs":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Org Hub Destinations Id Logs within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Hub Destinations Id Logs"},"delete":{"description":"Permanently removes or unlinks the target Org Hub Destinations Id Logs from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Delete Org Hub Destinations Id Logs"}},"/api/org":{"get":{"description":"Retrieves tenant organization profile, company name, address, default map coordinates, custom logo URL, coin balance, and active telemetry limits.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Organization settings.","content":{"application/json":{"example":{"success":true,"data":{"id":"90e544ce-d284-48f0-b8d4-63fcb001a1c5","name":"Xeekar Corp","logo_url":"https://cdn.vegagps.com/logos/xeekar.png","timezone":"Asia/Dhaka","currency":"BDT","coin_balance":1450,"speed_unit":"km/h"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Current Organization Settings & White-Label Config","security":[{"bearerAuth":[]}]},"put":{"description":"Updates company name, default map center, address, or notification settings.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Organization settings updated."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Xeekar Logistics Ltd."},"timezone":{"type":"string","example":"Asia/Dhaka"},"currency":{"type":"string","example":"BDT"}}},"example":{"name":"Xeekar Logistics Ltd.","timezone":"Asia/Dhaka"}}}},"tags":["Organizations"],"summary":"Update Organization Settings","security":[{"bearerAuth":[]}]}},"/api/org/upload-logo":{"post":{"description":"Provisions, dispatches, or creates a new Org Upload-logo in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Create or Trigger Org Upload-logo"}},"/api/org/connectors":{"get":{"description":"Retrieves a paginated list of Org Connectors accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Connectors"},"post":{"description":"Provisions, dispatches, or creates a new Org Connectors in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"example":"any"},"name":{"example":"any"},"config":{"example":"any"},"is_enabled":{"example":"any"},"is_default":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Create or Trigger Org Connectors"}},"/api/org/connectors/{id}":{"put":{"description":"Updates and overwrites properties of the target Org Connectors Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"config":{"example":"any"},"is_enabled":{"example":"any"},"is_default":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Connectors Id"},"delete":{"description":"Permanently removes or unlinks the target Org Connectors Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Delete Org Connectors Id"}},"/api/org/connectors/{id}/test":{"post":{"description":"Provisions, dispatches, or creates a new Org Connectors Id Test in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"test_recipient":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Create or Trigger Org Connectors Id Test"}},"/api/org/push-credentials":{"get":{"description":"Retrieves a paginated list of Org Push-credentials accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Push-credentials"},"put":{"description":"Updates and overwrites properties of the target Org Push-credentials.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"credentials":{"example":"any"},"project_id":{"example":"any"},"private_key":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Push-credentials"},"delete":{"description":"Permanently removes or unlinks the target Org Push-credentials from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Delete Org Push-credentials"}},"/api/org/push-credentials/test":{"post":{"description":"Provisions, dispatches, or creates a new Org Push-credentials Test in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"example":"any"},"title":{"example":"any"},"body":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Create or Trigger Org Push-credentials Test"}},"/api/org/children":{"get":{"description":"Retrieves a paginated list of Org Children accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Children"},"post":{"description":"Provisions, dispatches, or creates a new Org Children in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"plan":{"example":"any"},"adminEmail":{"example":"any"},"adminName":{"example":"any"},"adminPassword":{"example":"any"},"type":{"example":"any"},"slug":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Create or Trigger Org Children"}},"/api/org/tree":{"get":{"description":"Returns complete recursive organization hierarchy tree for reseller networks and enterprise holding groups.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Hierarchical tree of organizations."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Multi-Tenant Reseller / Sub-Organization Hierarchy Tree","security":[{"bearerAuth":[]}]}},"/api/org/children/{id}":{"put":{"description":"Updates and overwrites properties of the target Org Children Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"plan":{"example":"any"},"type":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Children Id"},"delete":{"description":"Permanently removes or unlinks the target Org Children Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Delete Org Children Id"}},"/api/org/children/{id}/status":{"patch":{"description":"Applies partial field modifications to the target Org Children Id Status.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Modify Org Children Id Status"}},"/api/org/children/{id}/users":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Org Children Id Users within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Children Id Users"}},"/api/org/children/{id}/branch":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Org Children Id Branch within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Children Id Branch"}},"/api/org/children/{orgId}/impersonate":{"post":{"description":"Provisions, dispatches, or creates a new Org Children OrgId Impersonate in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Create or Trigger Org Children OrgId Impersonate"}},"/api/org/exit-impersonation":{"post":{"description":"Provisions, dispatches, or creates a new Org Exit-impersonation in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Create or Trigger Org Exit-impersonation"}},"/api/org/api-keys":{"get":{"description":"Retrieves a paginated list of Org Api-keys accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Api-keys"},"post":{"description":"Provisions, dispatches, or creates a new Org Api-keys in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"expires_in":{"example":"any"},"allowed_vehicle_ids":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Create or Trigger Org Api-keys"}},"/api/org/api-keys/{id}":{"put":{"description":"Updates and overwrites properties of the target Org Api-keys Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"allowed_vehicle_ids":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Api-keys Id"},"delete":{"description":"Permanently removes or unlinks the target Org Api-keys Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Delete Org Api-keys Id"}},"/api/org/shareable":{"get":{"description":"Retrieves a paginated list of Org Shareable accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Shareable"}},"/api/analytics/overview":{"get":{"description":"Retrieves high-level executive fleet metrics: total fleet count, currently moving, idling, parked, offline, total kilometers driven today, and fuel consumed.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Executive dashboard KPIs.","content":{"application/json":{"example":{"success":true,"data":{"total_vehicles":42,"moving":18,"idling":4,"stopped":16,"offline":4,"total_km_today":3482.4,"fuel_consumed_liters_today":412.5,"active_alerts_count":3}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Fleet Operations Dashboard KPI Overview","security":[{"bearerAuth":[]}]}},"/api/analytics/charts":{"get":{"description":"Retrieves a paginated list of Analytics Charts accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Charts"}},"/api/analytics/trend":{"get":{"description":"Retrieves a paginated list of Analytics Trend accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Trend"}},"/api/analytics/drivers":{"get":{"description":"Calculates safety scorecards across all assigned fleet drivers, grading harsh braking, rapid acceleration, excessive speeding, and engine idling hours.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Ranked driver performance leaderboard."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Driver Safety & Performance Leaderboard","security":[{"bearerAuth":[]}]}},"/api/analytics/device-kpis":{"get":{"description":"Retrieves a paginated list of Analytics Device-kpis accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Device-kpis"}},"/api/analytics/fleet-health":{"get":{"description":"Retrieves a paginated list of Analytics Fleet-health accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Fleet-health"}},"/api/analytics/km-summary":{"get":{"description":"Retrieves a paginated list of Analytics Km-summary accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Km-summary"}},"/api/analytics/utilization":{"get":{"description":"Retrieves a paginated list of Analytics Utilization accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Utilization"}},"/api/analytics/utilization-trend":{"get":{"description":"Retrieves a paginated list of Analytics Utilization-trend accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Utilization-trend"}},"/api/analytics/heatmap":{"get":{"description":"Retrieves a paginated list of Analytics Heatmap accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Heatmap"}},"/api/analytics/fuel":{"get":{"description":"Returns aggregate fuel statistics, daily fleet fuel drain curve, detected refueling transactions, and potential fuel siphon/theft incidents.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"from","in":"query","description":"Start date","schema":{"type":"string","example":"2026-10-01"}},{"name":"to","in":"query","description":"End date","schema":{"type":"string","example":"2026-10-01"}}],"responses":{"200":{"description":"Fuel consumption and incident statistics."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Fleet-Wide Fuel Efficiency & Anomaly Analytics","security":[{"bearerAuth":[]}]}},"/api/analytics/fuel/morning-check":{"get":{"description":"Exception-first morning dispatch dashboard comparing fuel levels at evening park-up vs morning ignition. Flags vehicles that experienced overnight fuel drops while parked in yard or transit.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Morning fuel triage report with flagged theft drops.","content":{"application/json":{"example":{"success":true,"data":{"checked_vehicles":42,"overnight_thefts_detected":1,"items":[{"imei":"864540081293581","vehicle_name":"Toyota Allion 2024","park_time":"2026-09-30T22:00:00Z","park_fuel_liters":52,"morning_fuel_liters":38,"drop_liters":14,"flagged_as_theft":true}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Morning Fuel Check & Overnight Theft Triage","security":[{"bearerAuth":[]}]}},"/api/analytics/fuel/device/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Analytics Fuel Device Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Fuel Device Imei"}},"/api/analytics/fuel/events/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Analytics Fuel Events Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Fuel Events Imei"}},"/api/analytics/fuel/events/{id}/verify":{"patch":{"description":"Applies partial field modifications to the target Analytics Fuel Events Id Verify.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Modify Analytics Fuel Events Id Verify"}},"/api/analytics/fuel/sections/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Analytics Fuel Sections Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Fuel Sections Imei"}},"/api/analytics/fuel/raw/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Analytics Fuel Raw Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Fuel Raw Imei"}},"/api/analytics/temperature":{"get":{"description":"Monitors reefer cargo temperature trends across cold-chain fleet, flagging temperature excursions exceeding compliance thresholds (e.g. pharmaceuticals, frozen goods).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Cold chain compliance metrics and active excursion alerts."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Cold-Chain Reefer Cargo Temperature Analytics","security":[{"bearerAuth":[]}]}},"/api/analytics/temperature/device/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Analytics Temperature Device Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Temperature Device Imei"}},"/api/analytics/temperature/excursions":{"get":{"description":"Retrieves a paginated list of Analytics Temperature Excursions accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Temperature Excursions"}},"/api/analytics/temperature/excursions/{id}/acknowledge":{"post":{"description":"Provisions, dispatches, or creates a new Analytics Temperature Excursions Id Acknowledge in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Create or Trigger Analytics Temperature Excursions Id Acknowledge"}},"/api/analytics/temperature/trips":{"get":{"description":"Retrieves a paginated list of Analytics Temperature Trips accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Temperature Trips"}},"/api/analytics/temperature/trips/{id}/curve":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Analytics Temperature Trips Id Curve within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Temperature Trips Id Curve"}},"/api/analytics/driver-scores":{"get":{"description":"Retrieves a paginated list of Analytics Driver-scores accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Driver-scores"}},"/api/devices/exists/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Exists Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Exists Imei"}},"/api/devices":{"get":{"summary":"List Fleet Devices with Status & Filtering","description":"Retrieves a paginated list of all GPS trackers and vehicles accessible to the authenticated user's organization scope.\n\n### Filtering & Search\n- Filter by motion state: `status=moving`, `status=idle`, `status=stopped`, or `status=offline`.\n- Filter by fleet assignment: `fleet_id=123`.\n- Full-text search across vehicle name, license plate, or device IMEI.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","description":"Page number for pagination (starts at 1)","schema":{"type":"integer","default":1,"example":1}},{"name":"limit","in":"query","description":"Number of device records per page (max 1000)","schema":{"type":"integer","default":50,"example":25}},{"name":"search","in":"query","description":"Case-insensitive search matching vehicle name, plate number, or IMEI","schema":{"type":"string","example":"Allion"}},{"name":"status","in":"query","description":"Filter by current vehicle operational state","schema":{"type":"string","example":"moving","enum":["moving","idle","stopped","offline"]}},{"name":"fleet_id","in":"query","description":"Filter by fleet or sub-group identifier","schema":{"type":"string","example":"14"}}],"responses":{"200":{"description":"List of devices with pagination metadata.","content":{"application/json":{"example":{"success":true,"data":[{"imei":"864540081293581","name":"Toyota Allion 2024","plate_number":"DHK-METRO-GA-11-2041","model":"GT06Pro","vehicle_type":"car","fleet_id":14,"fleet_name":"Executive Fleet","online":true,"engine_on":true,"motion_state":"moving","speed":48,"lat":23.8103,"lon":90.4125,"last_seen":"2026-10-01T10:20:00Z","speed_limit":80}],"pagination":{"page":1,"limit":25,"total":42,"totalPages":2}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"security":[{"bearerAuth":[]}]},"post":{"summary":"Register New Tracking Device","description":"Provisions a new GPS tracking hardware device into the organization inventory.\n\n### Device Onboarding\nUpon registration, the device is immediately assigned to the tenant organization. The device IMEI must be unique across the platform.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Device registered successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"402":{"description":"Insufficient coin balance"},"403":{"description":"Forbidden"},"409":{"description":"Device with this IMEI is already registered."},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imei","name"],"properties":{"imei":{"type":"string","description":"15-digit unique hardware IMEI number","example":"864540081293581"},"name":{"type":"string","description":"Friendly vehicle or asset name","example":"Toyota Allion 2024"},"model":{"type":"string","description":"Hardware protocol/model identifier (e.g. GT06, Teltonika, Jimi, Coban)","example":"GT06Pro"},"vehicle_type":{"type":"string","enum":["car","truck","bus","motorcycle","van","tractor","trailer","ship","lock"],"example":"car"},"plate_number":{"type":"string","description":"Vehicle government license plate registration number","example":"DHK-METRO-GA-11-2041"},"fleet_id":{"type":"integer","description":"Optional fleet group assignment ID","example":14},"sim_number":{"type":"string","description":"Cellular SIM MSISDN phone number in device","example":"+8801712345678"},"speed_limit":{"type":"number","description":"Overspeed alert threshold in km/h","example":80},"tank_capacity":{"type":"number","description":"Total fuel tank capacity in liters (for fuel sensor calibration)","example":60}}},"example":{"imei":"864540081293581","name":"Toyota Allion 2024","model":"GT06Pro","vehicle_type":"car","plate_number":"DHK-METRO-GA-11-2041","speed_limit":80,"tank_capacity":60}}}},"tags":["Devices"],"security":[{"bearerAuth":[]}]}},"/api/devices/video":{"get":{"description":"Retrieves a paginated list of Devices Video accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Video"}},"/api/devices/positions":{"get":{"description":"High-frequency polling endpoint used by live tracking maps to retrieve updated coordinates, speed, heading, and motion state since a given timestamp.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"since","in":"query","description":"ISO-8601 UTC timestamp to receive only devices updated after this moment","schema":{"type":"string","example":"2026-10-01T10:15:00Z"}}],"responses":{"200":{"description":"Array of updated vehicle positions and states."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Real-Time Delta Positions for Tracking Map","security":[{"bearerAuth":[]}]}},"/api/devices/expiring":{"get":{"description":"Retrieves devices whose telematics service subscriptions will expire within the specified timeframe (default 30 days), facilitating proactive renewal outreach.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"days","in":"query","description":"Lookahead threshold in days (default: 30)","schema":{"type":"integer","default":30,"example":30}}],"responses":{"200":{"description":"List of expiring devices and days remaining."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"List Devices with Expiring Subscriptions (Next 30 Days)","security":[{"bearerAuth":[]}]}},"/api/devices/health":{"get":{"description":"Evaluates device reporting consistency, GPS fix validity, cellular signal quality (CSQ), and battery level across the fleet to highlight unhealthy hardware.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Fleet health scores and connectivity summary."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Fleet Telemetry Health & Connectivity Diagnostics","security":[{"bearerAuth":[]}]}},"/api/devices/personas":{"get":{"description":"Retrieves a paginated list of Devices Personas accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Personas"}},"/api/devices/models":{"get":{"description":"Retrieves a paginated list of Devices Models accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Models"},"post":{"description":"Provisions, dispatches, or creates a new Devices Models in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Create or Trigger Devices Models"}},"/api/devices/models/{id}":{"put":{"description":"Updates and overwrites properties of the target Devices Models Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Update Devices Models Id"},"delete":{"description":"Permanently removes or unlinks the target Devices Models Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Delete Devices Models Id"}},"/api/devices/transport-models":{"get":{"description":"Retrieves a paginated list of Devices Transport-models accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Transport-models"},"post":{"description":"Provisions, dispatches, or creates a new Devices Transport-models in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Create or Trigger Devices Transport-models"}},"/api/devices/assignment-counts":{"get":{"description":"Retrieves a paginated list of Devices Assignment-counts accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Assignment-counts"}},"/api/devices/{imei}":{"get":{"description":"Retrieves full configuration, current telemetry, sensor port mappings, assigned driver, odometer, engine hours, and subscription validity for a specific tracker.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Complete device profile and telemetry state.","content":{"application/json":{"example":{"success":true,"data":{"imei":"864540081293581","name":"Toyota Allion 2024","plate_number":"DHK-METRO-GA-11-2041","model":"GT06Pro","vehicle_type":"car","engine_on":true,"speed":48,"lat":23.8103,"lon":90.4125,"odometer_km":18450.2,"total_engine_hours":482.5,"speed_limit":80,"tank_capacity":60,"battery_voltage":13.8,"battery_percent":100,"subscription_end":"2027-10-01T00:00:00Z"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Device not found."},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Detailed Single Device Profile & Hardware Telemetry","security":[{"bearerAuth":[]}]},"put":{"description":"Updates vehicle metadata, plate number, assigned driver, speed limits, or fuel tank capacity.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Device profile updated successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Update Device Settings, Plate & Calibration","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Toyota Allion VIP"},"plate_number":{"type":"string","example":"DHK-METRO-GA-11-2041"},"speed_limit":{"type":"number","example":80},"tank_capacity":{"type":"number","example":60},"fleet_id":{"type":"integer","example":14}}},"example":{"name":"Toyota Allion VIP","plate_number":"DHK-METRO-GA-11-2041","speed_limit":80,"tank_capacity":60}}}}},"delete":{"description":"Deletes a device from the organization. Historical positions and trips are archived.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Device successfully removed."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Delete or Unregister Device","security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/daily-stats":{"get":{"tags":["Devices"],"summary":"Get Daily Mileage & Engine Hours (Weekly Mobile Overview)","description":"Retrieves a continuous, zero-filled daily time series of distance traveled, engine hours, driving time, idle duration, stop duration, and trip count.\n \n### Zero-Filling Guarantee\n- Ensures every single calendar date within the requested range has an entry, even if the vehicle had battery disconnected or was offline.\n- Designed specifically for 7-day mobile overview charts (*Travel Overview* and *Engine Hours*).","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"from","description":"Start date in YYYY-MM-DD format (defaults to 6 days ago for a 7-day window)","required":false,"example":"2026-09-26","in":"query","schema":{"type":"string","example":"2026-09-26"}},{"name":"to","description":"End date in YYYY-MM-DD format (defaults to today)","required":false,"example":"2026-10-02","in":"query","schema":{"type":"string","example":"2026-10-02"}},{"name":"timezone","description":"IANA timezone for day boundaries (defaults to organization timezone or Asia/Dhaka)","required":false,"in":"query","schema":{"type":"string","example":"Asia/Dhaka"}},{"name":"format","in":"query","description":"Output format: \"human\" for formatted unit strings (e.g. \"3.69 km\", \"45m\", \"23h 45m\") or \"raw\" for pure decimals (defaults to human)","schema":{"type":"string","enum":["human","raw"],"default":"human"}}],"responses":{"200":{"description":"Daily metrics successfully retrieved"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/installation-status":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Installation-status within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Imei Installation-status"}},"/api/devices/{imei}/current-trip":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Current-trip within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Imei Current-trip"}},"/api/devices/{imei}/dtc":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Dtc within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Imei Dtc"}},"/api/devices/{imei}/audit-logs":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Audit-logs within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Imei Audit-logs"}},"/api/devices/{imei}/assigned-users":{"get":{"description":"Retrieves all client user profiles currently granted access to view and monitor this vehicle.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of assigned users.","content":{"application/json":{"example":{"success":true,"data":[{"id":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","name":"Customer Name","email":"customer@example.com","role":"viewer"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"List Users Assigned to Device","security":[{"bearerAuth":[]}]},"put":{"description":"Assigns or replaces the list of client users who are permitted to track this vehicle. Replaces all existing user assignments for this vehicle with the provided list of user IDs.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Device user assignments updated.","content":{"application/json":{"example":{"success":true,"message":"Device users updated successfully"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_ids"],"properties":{"user_ids":{"type":"array","items":{"type":"string","format":"uuid","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b"},"description":"Array of user UUIDs who should have access to this device"}}},"example":{"user_ids":["c1f7b76e-347f-44de-9e5c-0c153b664d4b"]}}}},"tags":["Devices"],"summary":"Assign / Replace Users for Device","security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/duplicate":{"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Duplicate in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Create or Trigger Devices Imei Duplicate"}},"/api/devices/{imei}/fleet":{"put":{"description":"Updates and overwrites properties of the target Devices Imei Fleet.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Update Devices Imei Fleet"}},"/api/devices/{imei}/sensor-setup-complete":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Sensor-setup-complete.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Modify Devices Imei Sensor-setup-complete"}},"/api/devices/{imei}/subscription":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Subscription.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Modify Devices Imei Subscription"}},"/api/devices/{imei}/renew":{"post":{"description":"Extends the active telematics subscription for a device by deducting prepaid coins from the organization balance. 1 coin extends subscription by 12 months (365 days). If expired, the new expiry starts from today; if still active, 12 months are appended to current expiration date.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Subscription extended successfully.","content":{"application/json":{"example":{"success":true,"message":"Subscription extended by 12 months","data":{"imei":"864540081293581","subscription_end":"2027-10-05T00:00:00.000Z","coins_deducted":1,"remaining_balance":1449}}}}},"401":{"description":"Unauthorized"},"402":{"description":"Insufficient coin balance in organization."},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Renew Device Telematics Subscription (Coins)","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"coins":{"type":"integer","default":1,"example":1,"description":"Number of prepaid coins to consume (1 coin = 12 months)"}}},"example":{"coins":1}}}}}},"/api/devices/{imei}/status":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Status.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Modify Devices Imei Status"}},"/api/devices/{imei}/speed-limit":{"patch":{"description":"Sets the maximum permissible speed in km/h for the vehicle. Speeds exceeding this threshold trigger automated alerts.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Speed limit threshold updated."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Configure Vehicle Overspeed Alert Threshold","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["speed_limit"],"properties":{"speed_limit":{"type":"number","example":80}}},"example":{"speed_limit":80}}}}}},"/api/devices/{imei}/shares":{"get":{"description":"Retrieves active temporary tracking links or cross-organization device shares created for this tracker.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of active location shares."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"List Public / Cross-Tenant Location Shares for Device","security":[{"bearerAuth":[]}]},"post":{"description":"Creates a time-expiring public URL (with optional PIN or password) allowing third-party customers or recipients to track vehicle arrival in real time.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Share link created with public token and URL."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Generate Temporary Public Live Tracking Link","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expires_in_hours"],"properties":{"expires_in_hours":{"type":"integer","default":24,"example":24},"recipient_name":{"type":"string","example":"Customer Acme Corp"}}},"example":{"expires_in_hours":24,"recipient_name":"Customer Acme Corp"}}}}}},"/api/devices/{imei}/shares/{shareId}":{"delete":{"description":"Permanently removes or unlinks the target Devices Imei Shares ShareId from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"shareId","in":"path","required":true,"schema":{"type":"string","example":"share_94fb21a"},"description":"Public location share token or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Delete Devices Imei Shares ShareId"}},"/api/devices/{imei}/change-imei":{"patch":{"description":"Swaps the underlying GPS tracker hardware IMEI while preserving the vehicle name, plate number, historical trips, sensors, and maintenance records intact.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Current 15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Hardware swapped successfully."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Swap / Replace Physical Device Hardware (Preserve Vehicle Data)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["new_imei"],"properties":{"new_imei":{"type":"string","example":"865167047241865"}}},"example":{"new_imei":"865167047241865"}}}}}},"/api/devices/{imei}/sensors":{"get":{"description":"Retrieves all active analog, digital, RS485, and BLE telemetry sensors attached to a specific tracker, including fuel probes, cargo temperature probes, and door inputs.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"showHidden","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Array of attached device sensors and calibration settings.","content":{"application/json":{"example":{"success":true,"data":[{"id":1,"device_id":"864540081293581","name":"Main Fuel Tank","port":"fuel_level","sensor_type":"fuel","unit":"L","value":48.5,"calibration_points":[{"raw":0,"val":0},{"raw":4095,"val":60}]}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"List Configured Physical & Virtual Sensors for Device","security":[{"bearerAuth":[]}]},"post":{"description":"Maps an incoming telemetry port (e.g. `fuel_level`, `analog1`, `ble_temp_1`, `di1`) to a human-readable sensor with calibration curve.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Sensor mapped successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","port","sensor_type"],"properties":{"name":{"type":"string","example":"Reefer Cargo Temp Probe"},"port":{"type":"string","example":"ble_temp_1"},"sensor_type":{"type":"string","enum":["fuel","temperature","door","voltage","custom"],"example":"temperature"},"unit":{"type":"string","example":"°C"},"formula":{"type":"string","example":"raw * 0.1"}}},"example":{"name":"Reefer Cargo Temp Probe","port":"ble_temp_1","sensor_type":"temperature","unit":"°C"}}}},"tags":["Sensors"],"summary":"Attach or Map Sensor to Device Hardware Port","security":[{"bearerAuth":[]}]},"delete":{"description":"Clears all configured sensor port mappings and calibration curves for a device back to factory defaults.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"All sensors reset."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Reset All Sensors for Device","security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/sensors/{id}/fleet-scan":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Sensors Id Fleet-scan within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"port","in":"query","schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Sensors Id Fleet-scan"}},"/api/devices/{imei}/sensors/{id}/bulk-assign":{"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Sensors Id Bulk-assign in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"port":{"example":"any"},"device_ids":{"example":"any"},"override":{"example":"any"},"label":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Create or Trigger Devices Imei Sensors Id Bulk-assign"}},"/api/devices/{imei}/sensors/{id}":{"put":{"description":"Updates and overwrites properties of the target Devices Imei Sensors Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"unit":{"example":"any"},"formula_a":{"example":"any"},"formula_b":{"example":"any"},"min_value":{"example":"any"},"max_value":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Update Devices Imei Sensors Id"},"delete":{"description":"Permanently removes or unlinks the target Devices Imei Sensors Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Devices Imei Sensors Id"}},"/api/devices/{imei}/sensors/setup-summary":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Sensors Setup-summary within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Sensors Setup-summary"}},"/api/devices/{imei}/sensors/live":{"get":{"description":"Returns the latest calibrated sensor values evaluated through active math formulas and calibration tables.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Current calibrated sensor values.","content":{"application/json":{"example":{"success":true,"data":{"fuel_level":{"value":48.5,"unit":"L","formatted":"48.5 L"},"temperature":{"value":-18.2,"unit":"°C","formatted":"-18.2 °C"},"door":{"value":false,"formatted":"Closed"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Real-Time Live Calibrated Sensor Readings","security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/sensors/detected-ports":{"get":{"description":"Inspects raw incoming binary telemetry packets for this device to identify hardware ports (analog inputs, CAN-bus PIDs, BLE sensor beacons) that are transmitting data but not yet assigned to a display sensor.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of detected telemetry attributes available for mapping.","content":{"application/json":{"example":{"success":true,"data":[{"port":"analog1","latest_raw":3412,"inferred_type":"fuel"},{"port":"ble_temp_1","latest_raw":215,"inferred_type":"temperature"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Discover Unmapped Hardware Telemetry Ports","security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/sensors/visibility":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Sensors Visibility.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ports":{"example":"any"},"active":{"example":"any"},"mode":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Modify Devices Imei Sensors Visibility"}},"/api/devices/{imei}/sensors/{port}":{"put":{"description":"Updates polynomial formula, linear interpolation points, or display labels for an assigned sensor port.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Port identifier (e.g. fuel_level, analog1, temp1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Sensor configuration updated."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"example":"any"},"template_id":{"example":"any"},"formula_a":{"example":"any"},"formula_b":{"example":"any"},"calibration_table":{"example":"any"},"active":{"example":"any"},"favorite":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Update Sensor Calibration Table & Port Settings","security":[{"bearerAuth":[]}]},"delete":{"description":"Removes a sensor port assignment from a device.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Port identifier"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Sensor port removed."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Unmap Sensor Port","security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/sensors/{port}/readings":{"get":{"description":"Retrieves historical sensor time-series data (e.g. fuel drain slope, temperature logs) over a date range for graphing and analysis.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Port identifier"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"hours","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","description":"Start timestamp (ISO-8601 UTC)","schema":{"type":"string","example":"2026-10-01T00:00:00Z"}},{"name":"to","in":"query","description":"End timestamp (ISO-8601 UTC)","schema":{"type":"string","example":"2026-10-01T23:59:59Z"}}],"responses":{"200":{"description":"Time-series sensor readings."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Query Historical Sensor Readings Time-Series","security":[{"bearerAuth":[]}]},"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Sensors Port Readings in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"raw_value":{"example":"any"},"calibrated_value":{"example":"any"},"timestamp":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Create or Trigger Devices Imei Sensors Port Readings"}},"/api/devices/{imei}/sensors/{key}":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Sensors Key.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"battery_level"},"description":"Attribute or preference setting key"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"custom_label":{"example":"any"},"template_id":{"example":"any"},"hidden":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Modify Devices Imei Sensors Key"},"delete":{"description":"Permanently removes or unlinks the target Devices Imei Sensors Key from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"battery_level"},"description":"Attribute or preference setting key"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Devices Imei Sensors Key"}},"/api/devices/{imei}/detected-attributes":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Detected-attributes within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"showHidden","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Detected-attributes"},"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Detected-attributes in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"attribute_key":{"example":"any"},"raw_value":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Create or Trigger Devices Imei Detected-attributes"},"delete":{"description":"Permanently removes or unlinks the target Devices Imei Detected-attributes from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Devices Imei Detected-attributes"}},"/api/devices/{imei}/detected-attributes/{id}/fleet-scan":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Detected-attributes Id Fleet-scan within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"port","in":"query","schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Detected-attributes Id Fleet-scan"}},"/api/devices/{imei}/detected-attributes/{id}/bulk-assign":{"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Detected-attributes Id Bulk-assign in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"port":{"example":"any"},"device_ids":{"example":"any"},"override":{"example":"any"},"label":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Create or Trigger Devices Imei Detected-attributes Id Bulk-assign"}},"/api/devices/{imei}/detected-attributes/{id}":{"put":{"description":"Updates and overwrites properties of the target Devices Imei Detected-attributes Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"unit":{"example":"any"},"formula_a":{"example":"any"},"formula_b":{"example":"any"},"min_value":{"example":"any"},"max_value":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Update Devices Imei Detected-attributes Id"},"delete":{"description":"Permanently removes or unlinks the target Devices Imei Detected-attributes Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Devices Imei Detected-attributes Id"}},"/api/devices/{imei}/detected-attributes/setup-summary":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Detected-attributes Setup-summary within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Detected-attributes Setup-summary"}},"/api/devices/{imei}/detected-attributes/live":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Detected-attributes Live within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Detected-attributes Live"}},"/api/devices/{imei}/detected-attributes/detected-ports":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Detected-attributes Detected-ports within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Detected-attributes Detected-ports"}},"/api/devices/{imei}/detected-attributes/visibility":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Detected-attributes Visibility.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ports":{"example":"any"},"active":{"example":"any"},"mode":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Modify Devices Imei Detected-attributes Visibility"}},"/api/devices/{imei}/detected-attributes/{port}":{"put":{"description":"Updates and overwrites properties of the target Devices Imei Detected-attributes Port.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"example":"any"},"template_id":{"example":"any"},"formula_a":{"example":"any"},"formula_b":{"example":"any"},"calibration_table":{"example":"any"},"active":{"example":"any"},"favorite":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Update Devices Imei Detected-attributes Port"},"delete":{"description":"Permanently removes or unlinks the target Devices Imei Detected-attributes Port from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Devices Imei Detected-attributes Port"}},"/api/devices/{imei}/detected-attributes/{port}/readings":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Detected-attributes Port Readings within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"hours","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Detected-attributes Port Readings"},"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Detected-attributes Port Readings in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"raw_value":{"example":"any"},"calibrated_value":{"example":"any"},"timestamp":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Create or Trigger Devices Imei Detected-attributes Port Readings"}},"/api/devices/{imei}/detected-attributes/{key}":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Detected-attributes Key.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"battery_level"},"description":"Attribute or preference setting key"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"custom_label":{"example":"any"},"template_id":{"example":"any"},"hidden":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Modify Devices Imei Detected-attributes Key"},"delete":{"description":"Permanently removes or unlinks the target Devices Imei Detected-attributes Key from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"battery_level"},"description":"Attribute or preference setting key"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Devices Imei Detected-attributes Key"}},"/api/devices/{imei}/driver/scorecard":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Driver Scorecard within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"period","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}},{"name":"range","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Devices Imei Driver Scorecard"}},"/api/devices/{imei}/driver/scorecard/summary":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Driver Scorecard Summary within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"range","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Devices Imei Driver Scorecard Summary"}},"/api/devices/{imei}/driver/{id}/scores":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Driver Id Scores within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"range","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Devices Imei Driver Id Scores"}},"/api/devices/{imei}/driver/{id}/events":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Driver Id Events within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Devices Imei Driver Id Events"}},"/api/devices/{imei}/driver":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Driver within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Devices Imei Driver"},"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Driver in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"driver_id":{"example":"any"}}}}}},"tags":["Drivers"],"summary":"Create or Trigger Devices Imei Driver"}},"/api/devices/{imei}/driver/{id}":{"put":{"description":"Updates and overwrites properties of the target Devices Imei Driver Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"email":{"example":"any"},"phone":{"example":"any"}}}}}},"tags":["Drivers"],"summary":"Update Devices Imei Driver Id"},"delete":{"description":"Permanently removes or unlinks the target Devices Imei Driver Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Delete Devices Imei Driver Id"}},"/api/devices/{imei}/maintenance/upcoming":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Maintenance Upcoming within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Devices Imei Maintenance Upcoming"}},"/api/devices/{imei}/maintenance/alerts":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Maintenance Alerts within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"device_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Devices Imei Maintenance Alerts"}},"/api/devices/{imei}/maintenance/alerts/{id}/dismiss":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Maintenance Alerts Id Dismiss.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Modify Devices Imei Maintenance Alerts Id Dismiss"}},"/api/devices/{imei}/maintenance/digest":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Maintenance Digest within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Devices Imei Maintenance Digest"},"put":{"description":"Updates and overwrites properties of the target Devices Imei Maintenance Digest.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"frequency":{"example":"any"},"send_hour":{"example":"any"},"include_maintenance":{"example":"any"},"include_geofence":{"example":"any"},"include_speed":{"example":"any"},"include_sos":{"example":"any"},"email_override":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Update Devices Imei Maintenance Digest"}},"/api/devices/{imei}/maintenance/logs":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Maintenance Logs within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Devices Imei Maintenance Logs"},"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Maintenance Logs in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_id":{"example":"any"},"imei":{"example":"any"},"schedule_id":{"example":"any"},"type":{"example":"any"},"service_name":{"example":"any"},"service_date":{"example":"any"},"odometer":{"example":"any"},"odometer_km":{"example":"any"},"engine_hours":{"example":"any"},"cost":{"example":"any"},"notes":{"example":"any"},"performed_by":{"example":"any"},"workshop_name":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Create or Trigger Devices Imei Maintenance Logs"}},"/api/devices/{imei}/maintenance/schedules":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Maintenance Schedules within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Devices Imei Maintenance Schedules"},"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Maintenance Schedules in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"interval_value":{"example":"any"},"notify_km_before":{"example":"any"},"notify_days_before":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Create or Trigger Devices Imei Maintenance Schedules"}},"/api/devices/{imei}/maintenance/schedules/{id}/deactivate":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Maintenance Schedules Id Deactivate.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Modify Devices Imei Maintenance Schedules Id Deactivate"}},"/api/positions/{imei}":{"get":{"description":"Retrieves historical breadcrumb tracking coordinates, heading, speed, altitude, and sensor state for a device over a specific time range.\n \n### Spatial Downsampling & Filtering\n- **Outlier Filtering**: Automatically suppresses stationary GPS drift jitter (< 3 km/h anchor) and invalid speed spikes (> 150 km/h).\n- **LTTB (Largest Triangle Three Buckets)**: When querying long durations (e.g. 24h or 7 days), the API intelligently downsamples high-frequency points while preserving exact geometric road curves and turning points.\n- Query with `downsample=raw` or `downsample=0` to fetch 100% uncompressed raw points.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"example":100},"required":false,"description":"Maximum points to return when querying recent positions without date range (default: 100)"},{"name":"downsample","in":"query","schema":{"type":"string","example":"auto"},"required":false,"description":"Downsampling mode: \"auto\" (default, capped at 5000 pts), \"raw\" or \"0\" (full density), or target point count (e.g. 500)"},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"required":false,"description":"Start timestamp (ISO-8601 UTC)"},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"required":false,"description":"End timestamp (ISO-8601 UTC)"}],"responses":{"200":{"description":"Array of timestamped GPS position points.","content":{"application/json":{"example":{"success":true,"data":[{"time":"2026-10-01T10:14:00Z","imei":"864540081293581","lat":23.8103,"lon":90.4125,"speed":48,"course":180,"altitude":12,"satellites":14,"gps_valid":true,"raw_data":{"ignition":true,"external_voltage":13.8}}],"meta":{"total_positions":1420,"downsampled_to":1420,"algorithm":"raw_full_fidelity"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Position history locked — subscription expired."},"404":{"description":"Device not found."},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Positions"],"summary":"Get GPS Position History with LTTB Spatial Downsampling","security":[{"bearerAuth":[]}]}},"/api/positions/{imei}/latest":{"get":{"description":"Retrieves the single most recent telemetry packet for a vehicle. Uses an in-memory Redis cache (`device:last_pos:{imei}`) for sub-millisecond response latency, with automatic fallback to indexed storage.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Latest vehicle telemetry position and sensor snapshot.","content":{"application/json":{"example":{"success":true,"data":{"imei":"864540081293581","lat":23.8103,"lon":90.4125,"speed":52,"course":175,"ignition":true,"time":"2026-10-01T10:20:15Z","server_time":"2026-10-01T10:20:16Z","address":"Airport Road, Kurmitola, Dhaka","battery_voltage":13.8,"fuel_level":48.5}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Device or positions not found."},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Positions"],"summary":"Get Real-Time Latest Known Position (Sub-Millisecond Redis)","security":[{"bearerAuth":[]}]}},"/api/positions/{imei}/stops":{"get":{"description":"Computes stationary periods and parking stops where the vehicle was stationary with or without engine idling, including start time, end time, duration, and reverse geocoded address.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"},{"name":"min_minutes","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Array of detected vehicle stop events.","content":{"application/json":{"example":{"success":true,"data":[{"lat":23.7808,"lon":90.4152,"address":"Gulshan 2 Circle, Dhaka","start_time":"2026-10-01T08:15:00Z","end_time":"2026-10-01T09:00:00Z","duration_seconds":2700}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Positions"],"summary":"Get Vehicle Parking & Stop Duration Intervals","security":[{"bearerAuth":[]}]}},"/api/fleets/tree":{"get":{"description":"Returns nested parent-child fleet hierarchy with recursive path indexing, depth level, and aggregate device counts for building tree navigation menus and organizational charts.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"all"},"description":"Scope level: \"my\" (default), \"child\", or \"all\""}],"responses":{"200":{"description":"Hierarchical tree of fleet nodes.","content":{"application/json":{"example":{"success":true,"data":[{"id":14,"name":"Executive Fleet","depth":0,"device_count":12,"child_count":2,"path":"14","sort_path":"Executive Fleet"},{"id":22,"name":"Dhaka Division","depth":1,"parent_id":14,"device_count":6,"child_count":0,"path":"14.22","sort_path":"Executive Fleet/Dhaka Division"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fleets"],"summary":"Get Hierarchical Fleet Tree Structure","security":[{"bearerAuth":[]}]}},"/api/fleets":{"get":{"description":"Retrieves all fleet groups accessible to the current tenant user, annotated with active device counts. Supports filtering by organization scope (`scope=child` or `scope=all`).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Scope level: \"my\" (default), \"child\" (include sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of fleet groups.","content":{"application/json":{"example":{"success":true,"data":[{"id":14,"org_id":"90e544ce-d284-48f0-b8d4-63fcb001a1c5","name":"Executive Fleet","parent_id":null,"color":"#3b82f6","device_count":12,"org_name":"Xeekar Corp"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fleets"],"summary":"List All Fleets (Flat Array with Vehicle Counts)","security":[{"bearerAuth":[]}]},"post":{"description":"Creates a new logical vehicle group or sub-fleet under the organization hierarchy.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Fleet created successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Delivery Vans North"},"parent_id":{"type":"integer","description":"Parent fleet ID for nested grouping","example":14},"color":{"type":"string","description":"Hex color badge code","example":"#10b981"}}},"example":{"name":"Delivery Vans North","parent_id":14,"color":"#10b981"}}}},"tags":["Fleets"],"summary":"Create New Fleet Group","security":[{"bearerAuth":[]}]}},"/api/fleets/{id}":{"put":{"description":"Modifies the display name, nesting parent group, or accent badge color of a fleet.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","example":14},"description":"Fleet numeric ID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Fleet updated successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"VIP Executive Fleet"},"parent_id":{"type":"integer","example":null},"color":{"type":"string","example":"#6366f1"}}},"example":{"name":"VIP Executive Fleet","color":"#6366f1"}}}},"tags":["Fleets"],"summary":"Update Fleet Name, Parent & Color","security":[{"bearerAuth":[]}]},"delete":{"description":"Deletes a fleet group. Sub-fleets must be deleted first. Any devices assigned to this fleet have their `fleet_id` reset to NULL.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","example":14},"description":"Fleet numeric ID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Fleet deleted successfully."},"400":{"description":"Cannot delete fleet containing active sub-fleets."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fleets"],"summary":"Delete Fleet Group","security":[{"bearerAuth":[]}]}},"/api/groups/tree":{"get":{"description":"Retrieves a paginated list of Groups Tree accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fleets"],"summary":"Get Groups Tree"}},"/api/groups":{"get":{"description":"Retrieves a paginated list of Groups accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fleets"],"summary":"Get Groups"},"post":{"description":"Provisions, dispatches, or creates a new Groups in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"parent_id":{"example":"any"},"color":{"example":"any"}}}}}},"tags":["Fleets"],"summary":"Create or Trigger Groups"}},"/api/groups/{id}":{"put":{"description":"Updates and overwrites properties of the target Groups Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"parent_id":{"example":"any"},"color":{"example":"any"}}}}}},"tags":["Fleets"],"summary":"Update Groups Id"},"delete":{"description":"Permanently removes or unlinks the target Groups Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fleets"],"summary":"Delete Groups Id"}},"/api/geofences/categories":{"get":{"description":"Retrieves a paginated list of Geofences Categories accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Geofences"],"summary":"Get Geofences Categories"}},"/api/geofences":{"get":{"description":"Retrieves virtual perimeter boundaries configured for the organization, including center coordinates, radius, polygon GeoJSON coordinates, and category badges.\n\n### Multi-Tenant User Scoping\n- **Tenant Admins**: Can view all organization geofences across all users and fleets.\n- **Retail Users / Viewers**: Strictly scoped to private geofences they created (`created_by = userId`) plus public geofences (`category = 'public'`). Admin or other sub-user zones are isolated to prevent cross-account clutter.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"exclude_category","in":"query","schema":{"type":"string"}},{"name":"imei","in":"query","schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"category_id","in":"query","description":"Filter by geofence category ID","schema":{"type":"string","example":"depot"}}],"responses":{"200":{"description":"List of configured geofence shapes.","content":{"application/json":{"example":{"success":true,"data":[{"id":"4b5b9c44-979d-4c34-a877-564ea67fe7b4","name":"Central Logistics Yard","type":"circle","category":"general","color":"#3b82f6","created_by":"b6eb3d44-48d9-435f-bd59-2e51e0a27007","coordinates":{"center":[23.8103,90.4125],"radius":500},"speed_limit":20}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Geofences"],"summary":"List Organization Geofences (Circles & Polygons)","security":[{"bearerAuth":[]}]},"post":{"description":"Draws and saves a virtual geographic perimeter for monitoring vehicle entry, exit, dwell time, and localized speed limits. Automatically tags `created_by` to the authenticated user ID.\n \n### Geometry Formats\n- **Circle**: Requires `coordinates: { center: [lat, lon], radius: number }` or separate top-level `center_lat`, `center_lng`, and `radius` parameters.\n- **Polygon**: Requires `coordinates: [[lat, lon], [lat, lon], ...]` forming a closed boundary (minimum 3 coordinates).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Geofence created successfully with created_by user attribution."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string","example":"Central Logistics Yard"},"type":{"type":"string","enum":["circle","polygon"],"example":"circle"},"color":{"type":"string","default":"#FF0000","example":"#3b82f6"},"category":{"type":"string","default":"general","example":"depot"},"coordinates":{"type":"object","description":"Coordinates object (circle: { center: [lat, lng], radius: number }; polygon: [[lat, lng], ...])","example":{"center":[23.8103,90.4125],"radius":500}},"center_lat":{"type":"number","example":23.8103},"center_lng":{"type":"number","example":90.4125},"radius":{"type":"number","example":500},"speed_limit":{"type":"number","description":"Yard speed limit in km/h","example":20}}},"example":{"name":"Central Logistics Yard","type":"circle","coordinates":{"center":[23.8103,90.4125],"radius":500},"category":"general","color":"#3b82f6"}}}},"tags":["Geofences"],"summary":"Create Circular or Polygonal Geofence","security":[{"bearerAuth":[]}]}},"/api/geofences/import":{"post":{"description":"Uploads and parses a standard Google Earth KML file or GeoJSON feature collection to batch-create multiple geofences and highway transit corridors in one step.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Batch import summary with imported count.","content":{"application/json":{"example":{"success":true,"data":{"importedCount":12,"errors":[]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Geofences"],"summary":"Batch Import Geofences from KML or GeoJSON File","security":[{"bearerAuth":[]}]}},"/api/geofences/{id}":{"put":{"description":"Updates coordinates, radius, or metadata of an existing geofence.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"gf-central-depot"},"description":"Geofence UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Geofence updated."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"coordinates":{"example":"any"},"color":{"example":"any"},"category":{"example":"any"},"center_lat":{"example":"any"},"center_lng":{"example":"any"},"radius":{"example":"any"},"polygon":{"example":"any"}}}}}},"tags":["Geofences"],"summary":"Update Geofence Geometry, Name & Parameters","security":[{"bearerAuth":[]}]},"delete":{"description":"Permanently deletes a geofence and decouples it from any attached alert rules.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"gf-central-depot"},"description":"Geofence UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Geofence deleted."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Geofences"],"summary":"Delete Geofence","security":[{"bearerAuth":[]}]}},"/api/alerts":{"get":{"description":"Retrieves security and telematics alert events triggered across the fleet (overspeed, geofence enter/exit, harsh braking, panic SOS, ignition tampering).\n \n### Filtering\n- Filter by `status=active` or `status=acknowledged`.\n- Filter by severity: `critical`, `warning`, `info`.\n- Filter by specific vehicle IMEI or date range.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"integer","default":1,"example":1},"description":"Pagination page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"example":25},"description":"Number of alert records per page"},{"name":"type","in":"query","schema":{"type":"string","example":"overspeed"},"description":"Alert rule trigger type (e.g. overspeed, geofence_exit, sos, harsh_brake)"},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"},{"name":"search","in":"query","schema":{"type":"string","example":"Toyota"},"description":"Search filter keyword"},{"name":"sort","in":"query","schema":{"type":"string"}},{"name":"include_children","in":"query","schema":{"type":"string"}},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"has_video","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by acknowledgment status","schema":{"type":"string","example":"active","enum":["active","acknowledged","all"]}},{"name":"severity","in":"query","description":"Filter by alert severity","schema":{"type":"string","enum":["critical","warning","info"],"example":"critical"}},{"name":"imei","in":"query","description":"Filter to a specific vehicle IMEI","schema":{"type":"string","example":"864540081293581"}}],"responses":{"200":{"description":"Paginated list of alert event records.","content":{"application/json":{"example":{"success":true,"data":[{"id":"8a9c2d1e-45fa-43bc-91e8-71e89dfb6102","type":"overspeed","severity":"critical","title":"Speed Violation: 94 km/h","description":"Vehicle exceeded 80 km/h threshold on Airport Highway","device_id":"864540081293581","vehicle_name":"Toyota Allion 2024","status":"active","lat":23.8103,"lon":90.4125,"created_at":"2026-10-01T10:14:20Z"}],"pagination":{"page":1,"limit":25,"total":14,"totalPages":1}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"List Fleet Alert History with Filtering & Pagination","security":[{"bearerAuth":[]}]},"post":{"description":"Dispatches an instant high-priority SOS emergency alert from mobile app or in-cab panic button, alerting dispatchers and pushing priority push/SMS notifications.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"SOS alert broadcasted successfully."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imei"],"properties":{"imei":{"type":"string","example":"864540081293581"},"latitude":{"type":"number","example":23.8103},"longitude":{"type":"number","example":90.4125},"message":{"type":"string","example":"Emergency driver assistance requested"}}},"example":{"imei":"864540081293581","latitude":23.8103,"longitude":90.4125,"message":"Emergency driver assistance requested"}}}},"tags":["Alerts"],"summary":"Trigger Driver Emergency SOS / Panic Alert","security":[{"bearerAuth":[]}]}},"/api/alerts/history":{"get":{"description":"Retrieves a paginated list of Alerts History accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"},{"name":"search","in":"query","schema":{"type":"string","example":"Toyota"},"description":"Search filter keyword"},{"name":"sort","in":"query","schema":{"type":"string"}},{"name":"include_children","in":"query","schema":{"type":"string"}},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"has_video","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"Get Alerts History"}},"/api/alerts/sos":{"post":{"description":"Provisions, dispatches, or creates a new Alerts Sos in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"example":"any"},"latitude":{"example":"any"},"longitude":{"example":"any"},"lat":{"example":"any"},"lng":{"example":"any"},"lon":{"example":"any"},"device_imei":{"example":"any"},"deviceId":{"example":"any"},"timestamp":{"example":"any"},"message":{"example":"any"}}}}}},"tags":["Alerts"],"summary":"Create or Trigger Alerts Sos"}},"/api/alerts/acknowledge-all":{"put":{"description":"Updates and overwrites properties of the target Alerts Acknowledge-all.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"example":"any"},"type":{"example":"any"}}}}}},"tags":["Alerts"],"summary":"Update Alerts Acknowledge-all"},"post":{"description":"Clears or acknowledges all currently active alert notices for the organization in a single operation.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"All active alerts acknowledged."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"example":"any"},"type":{"example":"any"}}}}}},"tags":["Alerts"],"summary":"Bulk Acknowledge All Active Alerts","security":[{"bearerAuth":[]}]}},"/api/alerts/{id}/acknowledge":{"put":{"description":"Updates and overwrites properties of the target Alerts Id Acknowledge.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"Update Alerts Id Acknowledge"},"post":{"description":"Marks an individual alert as investigated and acknowledged by an operator, recording timestamp and user ID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"8a9c2d1e-45fa-43bc-91e8-71e89dfb6102"},"description":"Alert UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Alert marked as acknowledged."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"Acknowledge Specific Alert Event","security":[{"bearerAuth":[]}]}},"/api/alerts/{id}/ack":{"post":{"description":"Provisions, dispatches, or creates a new Alerts Id Ack in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"Create or Trigger Alerts Id Ack"}},"/api/alerts/rules":{"get":{"description":"Retrieves all automated notification and event detection rules created for the organization.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"includeTemplates","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of alert rules with trigger criteria and notification channels.","content":{"application/json":{"example":{"success":true,"data":[{"id":"rule-overspeed-80","name":"Highway Overspeed Alert","type":"overspeed","severity":"critical","enabled":true,"conditions":{"speed_limit":80,"duration_seconds":15},"channels":["push","email","sms"],"device_ids":["864540081293581"]}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"List Configured Alert Rules","security":[{"bearerAuth":[]}]},"post":{"description":"Configures a new telematics trigger condition that monitors live vehicle feeds and dispatches alerts upon violation.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Alert rule created successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string","example":"Highway Overspeed Alert"},"type":{"type":"string","enum":["overspeed","geofence_enter","geofence_exit","sos","power_cut","harsh_acceleration","harsh_braking","fuel_theft"],"example":"overspeed"},"severity":{"type":"string","enum":["critical","warning","info"],"default":"warning","example":"critical"},"config":{"type":"object","description":"Trigger threshold parameters (e.g. limit: 80, geofence_id, fuel_drop_liters). Can also be passed as \"conditions\".","example":{"limit":80}},"conditions":{"type":"object","description":"Alias for config parameter","example":{"speed_limit":80}},"notify_channels":{"type":"array","items":{"type":"string","enum":["push","email","sms","webhook"]},"example":["push","email"]},"channels":{"type":"array","items":{"type":"string","enum":["push","email","sms","webhook"]},"description":"Alias for notify_channels","example":["push","email"]},"device_ids":{"type":"array","items":{"type":"string"},"description":"List of assigned IMEIs, or omit for tenant-wide rule","example":["864540081293581"]},"cooldown_minutes":{"type":"number","default":10,"example":10}}},"example":{"name":"Highway Overspeed Alert","type":"overspeed","severity":"critical","config":{"limit":80},"notify_channels":["push","email"]}}}},"tags":["Alerts"],"summary":"Create Automated Alert Rule","security":[{"bearerAuth":[]}]}},"/api/alerts/rules/{id}":{"put":{"description":"Edits thresholds, assigned vehicle targets, or active notification channels for an alert rule.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"rule-overspeed-80"},"description":"Alert rule UUID or identifier"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Alert rule updated."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"config":{"example":"any"},"active":{"example":"any"},"device_ids":{"example":"any"},"fleet_ids":{"example":"any"},"cooldown_minutes":{"example":"any"},"schedule":{"example":"any"},"is_template":{"example":"any"},"template_name":{"example":"any"},"notify_channels":{"example":"any"}}}}}},"tags":["Alerts"],"summary":"Update Alert Rule Criteria & Channels","security":[{"bearerAuth":[]}]},"delete":{"description":"Permanently deactivates and removes an alert monitoring rule.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"rule-overspeed-80"},"description":"Alert rule identifier"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Alert rule deleted."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"Delete Alert Rule","security":[{"bearerAuth":[]}]}},"/api/alerts/templates":{"get":{"description":"Retrieves a paginated list of Alerts Templates accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"Get Alerts Templates"}},"/api/alerts/templates/apply":{"post":{"description":"Provisions, dispatches, or creates a new Alerts Templates Apply in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notifyChannels":{"example":"any"},"templateId":{"example":"any"},"deviceIds":{"example":"any"},"fleetIds":{"example":"any"},"notify_channels":{"example":"any"}}}}}},"tags":["Alerts"],"summary":"Create or Trigger Alerts Templates Apply"}},"/api/alerts/test-push":{"post":{"description":"Provisions, dispatches, or creates a new Alerts Test-push in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"Create or Trigger Alerts Test-push"}},"/api/commands/types":{"get":{"description":"Discovers all remote actuator commands supported by the platform and the target tracker hardware protocol (GT06, Jimi, Teltonika, Coban, JT808).\n \n### Command Capabilities\n- Returns standard parameters, dangerous level (e.g. engine cutoff), and channel support (GPRS TCP/UDP vs SMS).\n- Query with `?protocol=gt06` or `?protocol=teltonika` to narrow down to hardware-specific commands.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"protocol","in":"query","schema":{"type":"string","example":"gt06"},"description":"Hardware protocol identifier (e.g. gt06, teltonika, jt808, coban, meitrack, pilot)"}],"responses":{"200":{"description":"Array of supported command definitions with schemas and descriptions.","content":{"application/json":{"example":{"success":true,"data":[{"value":"relay_off","label":"Cut Off Engine (Relay Off)","description":"Activates external immobilizer relay to cut fuel pump / ignition","category":"security","dangerous":true},{"value":"relay_on","label":"Restore Engine (Relay On)","description":"Restores engine ignition relay to normal operational state","category":"security","dangerous":false},{"value":"reboot","label":"Restart Tracker Hardware","description":"Sends hardware reboot instruction to GSM/GPS module","category":"maintenance","dangerous":false},{"value":"custom","label":"Raw Protocol String / Custom AT Command","description":"Direct hex/string payload sent over active GPRS socket","category":"advanced","dangerous":true}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Commands"],"summary":"List Supported Hardware Command Types & Protocols","security":[{"bearerAuth":[]}]}},"/api/commands/templates":{"get":{"description":"Retrieves predefined reusable command presets configured for the tenant organization (e.g., standard ping intervals, immobilizer triggers, buzzer alerts).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of configured command templates.","content":{"application/json":{"example":{"success":true,"data":[{"id":3,"name":"Emergency Immobilize (Safe Stop)","protocol":"gt06","command_type":"relay_off","payload":"RELAY,1#","channel":"gprs","description":"Safely locks the vehicle engine upon next zero-speed event","created_at":"2026-09-15T08:30:00Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Commands"],"summary":"List Saved Organization Command Templates","security":[{"bearerAuth":[]}]},"post":{"description":"Saves a reusable command recipe for rapid dispatch across single or multiple devices in the fleet.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Template created successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","commandType"],"properties":{"name":{"type":"string","example":"Set Reporting 10s"},"protocol":{"type":"string","example":"gt06"},"commandType":{"type":"string","example":"custom"},"payload":{"type":"string","example":"TIMER,10,10#"},"parameters":{"type":"object","example":{"interval":10}},"description":{"type":"string","example":"Sets 10s moving interval"},"channel":{"type":"string","enum":["gprs","sms"],"example":"gprs"}}},"example":{"name":"Set Reporting 10s","protocol":"gt06","commandType":"custom","payload":"TIMER,10,10#","description":"Sets 10s moving interval","channel":"gprs"}}}},"tags":["Commands"],"summary":"Create Command Template","security":[{"bearerAuth":[]}]}},"/api/commands/templates/{id}":{"delete":{"description":"Removes an existing command preset from the organization catalog.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"3"},"description":"Command template UUID or numeric identifier"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Template deleted."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Template not found."},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Commands"],"summary":"Delete Command Template","security":[{"bearerAuth":[]}]}},"/api/commands/{imei}":{"get":{"description":"Retrieves the execution history of all remote commands dispatched to a specific tracker, including queue status (`queued`, `sent`, `executed`, `failed`), timestamps, and device replies.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device hardware IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of sent commands and their execution acknowledgments.","content":{"application/json":{"example":{"success":true,"data":[{"id":1084,"device_id":"864540081293581","command_type":"relay_off","command":"RELAY,1#","status":"executed","channel":"gprs","response":"Cut off the fuel supply success","sent_by_name":"Super Admin","created_at":"2026-10-01T10:14:02Z","delivered_at":"2026-10-01T10:14:03Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Commands"],"summary":"Get Command Audit Log & Delivery Status for Device","security":[{"bearerAuth":[]}]},"post":{"description":"Dispatches an instant control command to a live tracker over active TCP/UDP socket, or via Outbound SMS gateway if device is offline.\n \n### Safety & Permissions\n- **Engine Cutoff / Immobilization**: Requires explicit `commands:engine_cut` RBAC permission.\n- **Subscription Lock**: Devices with expired subscriptions cannot receive actuator commands.\n- Commands are pushed via Redis pub/sub directly to the connected telematics protocol gateway.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit target device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Command successfully queued or sent to the device.","content":{"application/json":{"example":{"success":true,"data":{"id":1085,"device_id":"864540081293581","command_type":"relay_off","status":"queued","channel":"gprs"}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Access denied: Subscription expired or user lacks commands:engine_cut permission."},"404":{"description":"Device not found in tenant organization."},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"commandType":{"type":"string","description":"Command type: relay_off, relay_on, reboot, position, or custom","example":"relay_off"},"channel":{"type":"string","enum":["gprs","sms"],"default":"gprs","description":"Transmission channel (GPRS is fast real-time socket; SMS is cellular fallback)","example":"gprs"},"templateId":{"type":"string","description":"Optional ID of preconfigured template to inherit parameters from","example":"3"},"params":{"type":"object","description":"Additional parameters or payload data for custom commands","example":{"state":"0","data":"RELAY,1#"}}}},"example":{"commandType":"relay_off","channel":"gprs","params":{"reason":"Unauthorized route deviation"}}}}},"tags":["Commands"],"summary":"Send Remote Hardware Command (GPRS / SMS)","security":[{"bearerAuth":[]}]}},"/api/commands/batch-preset":{"post":{"description":"Dispatches standard bulk commands across a fleet of devices simultaneously (e.g. disabling LBS cellular triangulation, configuring 10-second high-precision tracking, or static filtering).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Batch command dispatch summary.","content":{"application/json":{"example":{"success":true,"data":{"sentCount":2,"failedCount":0,"results":[{"imei":"864540081293581","status":"queued","commandLogId":1086},{"imei":"865167047241865","status":"queued","commandLogId":1087}]}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["presetId","imeis"],"properties":{"presetId":{"type":"string","description":"Preset key: _disable_lbs, _set_moving_interval_10s, _set_static_filter, _set_angle_upload, or custom string","example":"_set_moving_interval_10s"},"imeis":{"type":"array","items":{"type":"string"},"description":"Array of target 15-digit device IMEIs","example":["864540081293581","865167047241865"]}}},"example":{"presetId":"_set_moving_interval_10s","imeis":["864540081293581","865167047241865"]}}}},"tags":["Commands"],"summary":"Send Batch Configuration Preset to Multiple Devices","security":[{"bearerAuth":[]}]}},"/api/sensor-templates":{"get":{"description":"Retrieves library of reusable sensor configurations (fuel capacitive probes, ultrasonic sensors, digital temperature probes, door switches, axle load sensors) with standard formulas and scaling coefficients.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"showHidden","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of sensor templates.","content":{"application/json":{"example":{"success":true,"data":[{"id":"tmpl-dut-e-fuel","name":"Technoton DUT-E RS485 Fuel Sensor","sensor_type":"fuel","unit":"L","formula":"raw * 0.1","calibration_points":[{"raw":0,"val":0},{"raw":1023,"val":60}]}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"List Master Sensor Templates Catalog","security":[{"bearerAuth":[]}]},"post":{"description":"Defines a new standardized sensor profile with calibration curves, math formulas, and unit conversion for reuse across devices.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Sensor template created successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","sensor_type"],"properties":{"name":{"type":"string","example":"Omnicomm LLS Fuel Sensor"},"sensor_type":{"type":"string","enum":["fuel","temperature","door","ignition","battery","axle_load","engine_rpm","custom"],"example":"fuel"},"unit":{"type":"string","example":"L"},"formula":{"type":"string","example":"raw * 0.1"}}},"example":{"name":"Omnicomm LLS Fuel Sensor","sensor_type":"fuel","unit":"L","formula":"raw * 0.1"}}}},"tags":["Sensors"],"summary":"Create New Master Sensor Template","security":[{"bearerAuth":[]}]},"delete":{"description":"Permanently removes or unlinks the target Sensor-templates from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Sensor-templates"}},"/api/sensor-templates/{id}/fleet-scan":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Sensor-templates Id Fleet-scan within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"port","in":"query","schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Sensor-templates Id Fleet-scan"}},"/api/sensor-templates/{id}/bulk-assign":{"post":{"description":"Provisions, dispatches, or creates a new Sensor-templates Id Bulk-assign in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"port":{"example":"any"},"device_ids":{"example":"any"},"override":{"example":"any"},"label":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Create or Trigger Sensor-templates Id Bulk-assign"}},"/api/sensor-templates/{id}":{"put":{"description":"Updates calibration parameters, conversion formula, or units for a master sensor template.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"tmpl-dut-e-fuel"},"description":"Sensor template ID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Sensor template updated."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"unit":{"example":"any"},"formula_a":{"example":"any"},"formula_b":{"example":"any"},"min_value":{"example":"any"},"max_value":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Update Sensor Template Specification","security":[{"bearerAuth":[]}]},"delete":{"description":"Removes a sensor template from the catalog.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"tmpl-dut-e-fuel"},"description":"Sensor template ID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Sensor template deleted."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Sensor Template","security":[{"bearerAuth":[]}]}},"/api/sensor-templates/setup-summary":{"get":{"description":"Retrieves a paginated list of Sensor-templates Setup-summary accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Sensor-templates Setup-summary"}},"/api/sensor-templates/live":{"get":{"description":"Retrieves a paginated list of Sensor-templates Live accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Sensor-templates Live"}},"/api/sensor-templates/detected-ports":{"get":{"description":"Retrieves a paginated list of Sensor-templates Detected-ports accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Sensor-templates Detected-ports"}},"/api/sensor-templates/visibility":{"patch":{"description":"Applies partial field modifications to the target Sensor-templates Visibility.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ports":{"example":"any"},"active":{"example":"any"},"mode":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Modify Sensor-templates Visibility"}},"/api/sensor-templates/{port}":{"put":{"description":"Updates and overwrites properties of the target Sensor-templates Port.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"example":"any"},"template_id":{"example":"any"},"formula_a":{"example":"any"},"formula_b":{"example":"any"},"calibration_table":{"example":"any"},"active":{"example":"any"},"favorite":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Update Sensor-templates Port"},"delete":{"description":"Permanently removes or unlinks the target Sensor-templates Port from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Sensor-templates Port"}},"/api/sensor-templates/{port}/readings":{"get":{"description":"Retrieves a paginated list of Sensor-templates Port Readings accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"hours","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Sensor-templates Port Readings"},"post":{"description":"Provisions, dispatches, or creates a new Sensor-templates Port Readings in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"raw_value":{"example":"any"},"calibrated_value":{"example":"any"},"timestamp":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Create or Trigger Sensor-templates Port Readings"}},"/api/sensor-templates/{key}":{"patch":{"description":"Applies partial field modifications to the target Sensor-templates Key.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"battery_level"},"description":"Attribute or preference setting key"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"custom_label":{"example":"any"},"template_id":{"example":"any"},"hidden":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Modify Sensor-templates Key"},"delete":{"description":"Permanently removes or unlinks the target Sensor-templates Key from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"battery_level"},"description":"Attribute or preference setting key"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Sensor-templates Key"}},"/api/drivers/scorecard":{"get":{"description":"Calculates aggregate safety scores based on harsh acceleration, hard cornering, harsh braking, overspeed durations, and unnecessary idling.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"period","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}},{"name":"range","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Driver scorecards and penalty breakdown."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Safety & Eco-Driving Scorecard for All Drivers","security":[{"bearerAuth":[]}]}},"/api/drivers/scorecard/summary":{"get":{"description":"Retrieves a paginated list of Drivers Scorecard Summary accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"range","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Drivers Scorecard Summary"}},"/api/drivers/{id}/scores":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Drivers Id Scores within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"range","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Drivers Id Scores"}},"/api/drivers/{id}/events":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Drivers Id Events within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Drivers Id Events"}},"/api/drivers":{"get":{"description":"Retrieves all commercial drivers enrolled in the organization, including driving license number, expiration date, assigned vehicle, contact phone, and safety rating.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of drivers.","content":{"application/json":{"example":{"success":true,"data":[{"id":"drv-01","name":"Rahim Khan","license_number":"DL-84729104","license_expiry":"2028-05-12","phone":"+8801712345678","assigned_vehicle_imei":"864540081293581","safety_score":94}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"List Registered Fleet Drivers","security":[{"bearerAuth":[]}]},"post":{"description":"Registers a new driver into the fleet directory, with license details and emergency contacts.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"201":{"description":"Driver enrolled successfully."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Rahim Khan"},"email":{"type":"string","format":"email","description":"Driver login email (optional, auto-generated from phone if omitted)","example":"driver.rahim@xeekar.com"},"phone":{"type":"string","example":"+8801712345678"},"password":{"type":"string","minLength":4,"maxLength":10,"description":"Driver app login password","example":"Temp1234"},"license_number":{"type":"string","description":"Driving license number","example":"DL-84729104"},"license_expiry":{"type":"string","example":"2028-05-12"},"assigned_vehicle_imei":{"type":"string","example":"864540081293581"}}},"example":{"name":"Rahim Khan","phone":"+8801712345678","license_number":"DL-84729104","license_expiry":"2028-05-12","password":"Temp1234"}}}},"tags":["Drivers"],"summary":"Enroll New Driver Profile","security":[{"bearerAuth":[]}]}},"/api/drivers/{id}":{"put":{"description":"Modifies driver details, phone numbers, or license expiration renewal.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"drv-01"},"description":"Driver ID or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Driver profile updated."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"email":{"example":"any"},"phone":{"example":"any"}}}}}},"tags":["Drivers"],"summary":"Update Driver Profile & License Validity","security":[{"bearerAuth":[]}]},"delete":{"description":"Removes a driver from the system. Unassigns any currently linked vehicles.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"drv-01"},"description":"Driver ID or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Driver removed."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Delete Driver Profile","security":[{"bearerAuth":[]}]}},"/api/maintenance/upcoming":{"get":{"description":"Lists vehicles due for periodic servicing (engine oil change, brake pad inspection, tire rotation) based on odometer mileage, engine run hours, or calendar intervals.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of vehicles with due or overdue maintenance services.","content":{"application/json":{"example":{"success":true,"data":[{"imei":"864540081293581","vehicle_name":"Toyota Allion 2024","service_name":"Engine Oil & Filter Change","interval_km":5000,"current_odometer_km":18450,"due_at_km":20000,"km_remaining":1550,"status":"upcoming"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Upcoming Vehicle Maintenance & Service Schedules","security":[{"bearerAuth":[]}]}},"/api/maintenance/alerts":{"get":{"description":"Retrieves a paginated list of Maintenance Alerts accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"device_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Maintenance Alerts"}},"/api/maintenance/alerts/{id}/dismiss":{"patch":{"description":"Applies partial field modifications to the target Maintenance Alerts Id Dismiss.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Modify Maintenance Alerts Id Dismiss"}},"/api/maintenance/digest":{"get":{"description":"Retrieves a paginated list of Maintenance Digest accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Maintenance Digest"},"put":{"description":"Updates and overwrites properties of the target Maintenance Digest.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"frequency":{"example":"any"},"send_hour":{"example":"any"},"include_maintenance":{"example":"any"},"include_geofence":{"example":"any"},"include_speed":{"example":"any"},"include_sos":{"example":"any"},"email_override":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Update Maintenance Digest"}},"/api/maintenance/logs":{"get":{"description":"Retrieves historical maintenance records, invoices, parts replaced, and costs recorded by fleet mechanics.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of completed maintenance logs."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"List Maintenance Service History Logs","security":[{"bearerAuth":[]}]},"post":{"description":"Records a completed service event, resetting the service interval counter and archiving parts and workshop invoice costs.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Maintenance record saved and interval reset."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cost"],"properties":{"device_id":{"type":"string","description":"Device IMEI (or pass as imei)","example":"864540081293581"},"imei":{"type":"string","description":"Alias for device_id","example":"864540081293581"},"service_name":{"type":"string","description":"Description of service performed (or pass as type)","example":"Mobil 1 5W-30 Oil Change"},"type":{"type":"string","description":"Service type code (alias for service_name)","example":"general_service"},"cost":{"type":"number","example":4500},"odometer_km":{"type":"number","description":"Odometer reading (or pass as odometer)","example":18450},"odometer":{"type":"number","description":"Alias for odometer_km","example":18450},"workshop_name":{"type":"string","description":"Workshop name (or pass as performed_by)","example":"Navana Toyota Service Center"},"performed_by":{"type":"string","description":"Alias for workshop_name","example":"Navana Toyota Service Center"},"notes":{"type":"string","example":"Oil filter replaced; brake pads checked at 70%"}}},"example":{"imei":"864540081293581","service_name":"Mobil 1 5W-30 Oil Change","cost":4500,"odometer_km":18450,"workshop_name":"Navana Toyota Service Center"}}}},"tags":["Maintenance"],"summary":"Log Completed Service / Maintenance Event","security":[{"bearerAuth":[]}]}},"/api/maintenance/schedules":{"get":{"description":"Retrieves a paginated list of Maintenance Schedules accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Maintenance Schedules"},"post":{"description":"Provisions, dispatches, or creates a new Maintenance Schedules in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"interval_value":{"example":"any"},"notify_km_before":{"example":"any"},"notify_days_before":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Create or Trigger Maintenance Schedules"}},"/api/maintenance/schedules/{id}/deactivate":{"patch":{"description":"Applies partial field modifications to the target Maintenance Schedules Id Deactivate.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Modify Maintenance Schedules Id Deactivate"}},"/api/service-intervals/upcoming":{"get":{"description":"Retrieves a paginated list of Service-intervals Upcoming accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Service-intervals Upcoming"}},"/api/service-intervals/alerts":{"get":{"description":"Retrieves a paginated list of Service-intervals Alerts accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"device_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Service-intervals Alerts"}},"/api/service-intervals/alerts/{id}/dismiss":{"patch":{"description":"Applies partial field modifications to the target Service-intervals Alerts Id Dismiss.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Modify Service-intervals Alerts Id Dismiss"}},"/api/service-intervals/digest":{"get":{"description":"Retrieves a paginated list of Service-intervals Digest accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Service-intervals Digest"},"put":{"description":"Updates and overwrites properties of the target Service-intervals Digest.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"frequency":{"example":"any"},"send_hour":{"example":"any"},"include_maintenance":{"example":"any"},"include_geofence":{"example":"any"},"include_speed":{"example":"any"},"include_sos":{"example":"any"},"email_override":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Update Service-intervals Digest"}},"/api/service-intervals/logs":{"get":{"description":"Retrieves a paginated list of Service-intervals Logs accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Service-intervals Logs"},"post":{"description":"Provisions, dispatches, or creates a new Service-intervals Logs in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_id":{"example":"any"},"imei":{"example":"any"},"schedule_id":{"example":"any"},"type":{"example":"any"},"service_name":{"example":"any"},"service_date":{"example":"any"},"odometer":{"example":"any"},"odometer_km":{"example":"any"},"engine_hours":{"example":"any"},"cost":{"example":"any"},"notes":{"example":"any"},"performed_by":{"example":"any"},"workshop_name":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Create or Trigger Service-intervals Logs"}},"/api/service-intervals/schedules":{"get":{"description":"Retrieves a paginated list of Service-intervals Schedules accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Service-intervals Schedules"},"post":{"description":"Provisions, dispatches, or creates a new Service-intervals Schedules in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"interval_value":{"example":"any"},"notify_km_before":{"example":"any"},"notify_days_before":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Create or Trigger Service-intervals Schedules"}},"/api/service-intervals/schedules/{id}/deactivate":{"patch":{"description":"Applies partial field modifications to the target Service-intervals Schedules Id Deactivate.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Modify Service-intervals Schedules Id Deactivate"}},"/api/reports/types":{"get":{"description":"Discovers all available report generator templates in the platform (e.g. Trips Summary, Stop & Idle Durations, Daily Distance Traveled, Fuel Consumption & Thefts, Speed Violations, Driver Scorecard, Geofence In/Out).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Array of report templates with filter definitions and export formats (PDF, Excel, CSV)."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"List Supported Fleet Report Types","security":[{"bearerAuth":[]}]}},"/api/reports/scheduled":{"get":{"description":"Retrieves a paginated list of Reports Scheduled accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Get Reports Scheduled"},"post":{"description":"Provisions, dispatches, or creates a new Reports Scheduled in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"format":{"example":"any"},"device_ids":{"example":"any"},"data_items":{"example":"any"},"options":{"example":"any"},"frequency":{"example":"any"},"time_of_day":{"example":"any"},"day_of_week":{"example":"any"},"day_of_month":{"example":"any"},"timezone":{"example":"any"},"email_recipients":{"example":"any"}}}}}},"tags":["Reports"],"summary":"Create or Trigger Reports Scheduled"}},"/api/reports/scheduled/{id}":{"put":{"description":"Updates and overwrites properties of the target Reports Scheduled Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Update Reports Scheduled Id"},"delete":{"description":"Permanently removes or unlinks the target Reports Scheduled Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Delete Reports Scheduled Id"}},"/api/reports/scheduled/{id}/run-now":{"post":{"description":"Provisions, dispatches, or creates a new Reports Scheduled Id Run-now in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Create or Trigger Reports Scheduled Id Run-now"}},"/api/reports/trips":{"get":{"description":"Generates a detailed summary of all vehicle trips over a date range, with start/end timestamps, duration, distance (km), max speed, average speed, and idle time.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"snap_to_roads","in":"query","schema":{"type":"string"}},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"origin_geofence_id","in":"query","schema":{"type":"string"}},{"name":"destination_geofence_id","in":"query","schema":{"type":"string"}},{"name":"min_stop_minutes","in":"query","schema":{"type":"string"}},{"name":"imei","in":"query","description":"Target vehicle 15-digit IMEI (omit for entire fleet)","schema":{"type":"string","example":"864540081293581"}},{"name":"from","in":"query","required":true,"description":"Start date/time (ISO-8601 UTC)","schema":{"type":"string","example":"2026-10-01T00:00:00Z"}},{"name":"to","in":"query","required":true,"description":"End date/time (ISO-8601 UTC)","schema":{"type":"string","example":"2026-10-01T23:59:59Z"}}],"responses":{"200":{"description":"Trips summary report records."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Generate Trips & Distance Summary Report","security":[{"bearerAuth":[]}]}},"/api/reports/trip-route":{"get":{"description":"Retrieves a paginated list of Reports Trip-route accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"start_time","in":"query","schema":{"type":"string"}},{"name":"end_time","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Get Reports Trip-route"}},"/api/reports/generate":{"post":{"description":"Enqueues an asynchronous report generation task in the worker cluster. Supports heavy multi-month or whole-fleet queries and returns a job token to poll for PDF/Excel download readiness.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"202":{"description":"Report job accepted and processing in background."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","from","to"],"properties":{"type":{"type":"string","enum":["trips","stops","fuel","overspeed","geofence","mileage"],"example":"fuel"},"format":{"type":"string","enum":["pdf","xlsx","csv"],"default":"pdf","example":"pdf"},"from":{"type":"string","example":"2026-09-01T00:00:00Z"},"to":{"type":"string","example":"2026-09-30T23:59:59Z"},"device_ids":{"type":"array","items":{"type":"string"},"description":"Target vehicle device IMEIs","example":["864540081293581"]},"imeis":{"type":"array","items":{"type":"string"},"description":"Alias for device_ids","example":["864540081293581"]}}},"example":{"type":"fuel","format":"pdf","from":"2026-09-01T00:00:00Z","to":"2026-09-30T23:59:59Z"}}}},"tags":["Reports"],"summary":"Trigger Asynchronous Background Report Generation","security":[{"bearerAuth":[]}]}},"/api/reports/download/{filename}":{"get":{"description":"Downloads the compiled report document artifact using the filename generated by the background worker.","produces":[null],"parameters":[{"name":"filename","in":"path","required":true,"schema":{"type":"string","example":"fuel-report-20261001.pdf"},"description":"Report output filename (e.g. fuel-report-20261001.pdf)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Report binary file stream.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Download Generated PDF, Excel or CSV Report File","security":[{"bearerAuth":[]}]}},"/api/reports/create":{"post":{"description":"Provisions, dispatches, or creates a new Reports Create in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"format":{"example":"any"},"device_ids":{"example":"any"},"date_from":{"example":"any"},"date_to":{"example":"any"},"data_items":{"example":"any"},"options":{"example":"any"}}}}}},"tags":["Reports"],"summary":"Create or Trigger Reports Create"}},"/api/reports":{"get":{"description":"Retrieves a paginated list of Reports accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Get Reports"}},"/api/reports/settings":{"get":{"description":"Retrieves a paginated list of Reports Settings accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Get Reports Settings"},"put":{"description":"Updates and overwrites properties of the target Reports Settings.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"auto_delete_days":{"example":"any"},"auto_delete_enabled":{"example":"any"},"max_file_size_mb":{"example":"any"}}}}}},"tags":["Reports"],"summary":"Update Reports Settings"}},"/api/reports/settings/cleanup":{"post":{"description":"Provisions, dispatches, or creates a new Reports Settings Cleanup in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Create or Trigger Reports Settings Cleanup"}},"/api/reports/{id}/retry":{"post":{"description":"Provisions, dispatches, or creates a new Reports Id Retry in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Create or Trigger Reports Id Retry"}},"/api/reports/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Reports Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Get Reports Id"},"delete":{"description":"Permanently removes or unlinks the target Reports Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Delete Reports Id"}},"/api/tasks":{"get":{"description":"Retrieves a paginated list of Tasks accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"driver_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Tasks"],"summary":"Get Tasks"},"post":{"description":"Provisions, dispatches, or creates a new Tasks in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"example":"any"},"description":{"example":"any"},"device_id":{"example":"any"},"driver_id":{"example":"any"},"location_lat":{"example":"any"},"location_lon":{"example":"any"},"address":{"example":"any"},"due_at":{"example":"any"},"priority":{"example":"any"}}}}}},"tags":["Tasks"],"summary":"Create or Trigger Tasks"}},"/api/tasks/{id}":{"put":{"description":"Updates and overwrites properties of the target Tasks Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"example":"any"},"driver_id":{"example":"any"},"completed_at":{"example":"any"}}}}}},"tags":["Tasks"],"summary":"Update Tasks Id"},"delete":{"description":"Permanently removes or unlinks the target Tasks Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Tasks"],"summary":"Delete Tasks Id"}},"/api/tasks/{id}/status":{"patch":{"description":"Applies partial field modifications to the target Tasks Id Status.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"example":"any"},"origin_lat":{"example":"any"},"origin_lon":{"example":"any"}}}}}},"tags":["Tasks"],"summary":"Modify Tasks Id Status"}},"/api/tasks/{id}/eta":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Tasks Id Eta within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Tasks"],"summary":"Get Tasks Id Eta"}},"/api/routes":{"get":{"description":"Retrieves a paginated list of Routes accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Routes"],"summary":"Get Routes"},"post":{"description":"Provisions, dispatches, or creates a new Routes in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"waypoints":{"example":"any"},"color":{"example":"any"},"distance_km":{"example":"any"},"corridor_km":{"example":"any"}}}}}},"tags":["Routes"],"summary":"Create or Trigger Routes"}},"/api/routes/directions":{"post":{"description":"Provisions, dispatches, or creates a new Routes Directions in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"waypoints":{"example":"any"}}}}}},"tags":["Routes"],"summary":"Create or Trigger Routes Directions"}},"/api/routes/nearest":{"get":{"description":"Retrieves a paginated list of Routes Nearest accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"lat","in":"query","schema":{"type":"string"}},{"name":"lon","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Routes"],"summary":"Get Routes Nearest"}},"/api/routes/match":{"post":{"description":"Provisions, dispatches, or creates a new Routes Match in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"length":{"example":"any"},"req.body":{"example":"any"}}}}}},"tags":["Routes"],"summary":"Create or Trigger Routes Match"}},"/api/routes/{id}":{"put":{"description":"Updates and overwrites properties of the target Routes Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"waypoints":{"example":"any"},"color":{"example":"any"},"distance_km":{"example":"any"},"corridor_km":{"example":"any"}}}}}},"tags":["Routes"],"summary":"Update Routes Id"},"delete":{"description":"Permanently removes or unlinks the target Routes Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Routes"],"summary":"Delete Routes Id"}},"/api/pois":{"get":{"description":"Retrieves geographic points of interest (gas stations, customer delivery docks, resting areas, ports) with coordinate pins and contact numbers.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"category","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of POI markers."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["POI"],"summary":"List Points of Interest (POI) & Yard Waypoints","security":[{"bearerAuth":[]}]},"post":{"description":"Saves a new custom geographic landmark with category icon and radius.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"POI saved."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"category":{"example":"any"},"lat":{"example":"any"},"lon":{"example":"any"},"address":{"example":"any"},"icon":{"example":"any"},"color":{"example":"any"}}}}}},"tags":["POI"],"summary":"Create Point of Interest (POI)","security":[{"bearerAuth":[]}]}},"/api/pois/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Pois Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["POI"],"summary":"Get Pois Id"},"put":{"description":"Updates and overwrites properties of the target Pois Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"category":{"example":"any"},"lat":{"example":"any"},"lon":{"example":"any"},"address":{"example":"any"},"icon":{"example":"any"},"color":{"example":"any"}}}}}},"tags":["POI"],"summary":"Update Pois Id"},"delete":{"description":"Permanently removes or unlinks the target Pois Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["POI"],"summary":"Delete Pois Id"}},"/api/stats":{"get":{"description":"Retrieves a paginated list of Stats accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"range","in":"query","schema":{"type":"string"}},{"name":"deviceId","in":"query","schema":{"type":"string","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b"},"description":"Device UUID or hardware identifier"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Stats"],"summary":"Get Stats"}},"/api/stats/organizations":{"get":{"description":"Retrieves a paginated list of Stats Organizations accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Stats"],"summary":"Get Stats Organizations"}},"/api/organizations":{"get":{"description":"Retrieves a paginated list of Organizations accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"range","in":"query","schema":{"type":"string"}},{"name":"deviceId","in":"query","schema":{"type":"string","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b"},"description":"Device UUID or hardware identifier"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Organizations"}},"/api/organizations/organizations":{"get":{"description":"Retrieves a paginated list of Organizations Organizations accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Organizations Organizations"}},"/api/admin/unknown-devices":{"get":{"description":"Displays unassigned GPS trackers that have established a TCP/UDP connection and are sending packets to the gateway, but whose IMEIs have not yet been approved or mapped to an organization.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"}],"responses":{"200":{"description":"List of unapproved devices transmitting telemetry.","content":{"application/json":{"example":{"success":true,"data":[{"imei":"869281048201948","protocol":"gt06","ip":"103.24.12.5","port":5023,"packets_received":42,"first_seen":"2026-10-01T09:12:00Z","last_seen":"2026-10-01T10:15:20Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Unknown Devices"],"summary":"List Unrecognized Hardware in Quarantine Pool","security":[{"bearerAuth":[]}]}},"/api/admin/unknown-devices/count":{"get":{"description":"Retrieves a paginated list of Admin Unknown-devices Count accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Unknown Devices"],"summary":"Get Admin Unknown-devices Count"}},"/api/admin/unknown-devices/bulk-approve":{"post":{"description":"Provisions, dispatches, or creates a new Admin Unknown-devices Bulk-approve in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"}}}}}},"tags":["Unknown Devices"],"summary":"Create or Trigger Admin Unknown-devices Bulk-approve"}},"/api/admin/unknown-devices/{imei}/approve":{"post":{"description":"Provisions, dispatches, or creates a new Admin Unknown-devices Imei Approve in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"example":"any"}}}}}},"tags":["Unknown Devices"],"summary":"Create or Trigger Admin Unknown-devices Imei Approve"}},"/api/admin/unknown-devices/{imei}/reject":{"post":{"description":"Provisions, dispatches, or creates a new Admin Unknown-devices Imei Reject in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"example":"any"}}}}}},"tags":["Unknown Devices"],"summary":"Create or Trigger Admin Unknown-devices Imei Reject"}},"/api/admin/unknown-devices/{imei}/ignore":{"post":{"description":"Provisions, dispatches, or creates a new Admin Unknown-devices Imei Ignore in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Unknown Devices"],"summary":"Create or Trigger Admin Unknown-devices Imei Ignore"}},"/api/admin/unknown-devices/{imei}/restore":{"post":{"description":"Provisions, dispatches, or creates a new Admin Unknown-devices Imei Restore in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Unknown Devices"],"summary":"Create or Trigger Admin Unknown-devices Imei Restore"}},"/api/admin/unknown-devices/{imei}":{"delete":{"description":"Permanently removes or unlinks the target Admin Unknown-devices Imei from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Unknown Devices"],"summary":"Delete Admin Unknown-devices Imei"}},"/api/admin/simulator/models":{"get":{"description":"Retrieves a paginated list of Admin Simulator Models accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Simulator"],"summary":"Get Admin Simulator Models"}},"/api/admin/simulator/sensor-types":{"get":{"description":"Retrieves a paginated list of Admin Simulator Sensor-types accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Simulator"],"summary":"Get Admin Simulator Sensor-types"}},"/api/admin/simulator/behaviors":{"get":{"description":"Retrieves a paginated list of Admin Simulator Behaviors accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Simulator"],"summary":"Get Admin Simulator Behaviors"}},"/api/admin/simulator/profiles":{"get":{"description":"Retrieves a paginated list of Admin Simulator Profiles accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Simulator"],"summary":"Get Admin Simulator Profiles"}},"/api/admin/simulator/generate-imei":{"post":{"description":"Provisions, dispatches, or creates a new Admin Simulator Generate-imei in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Simulator"],"summary":"Create or Trigger Admin Simulator Generate-imei"}},"/api/admin/simulator":{"get":{"description":"Checks whether the built-in GPS telemetry simulator is actively generating synthetic road movement for demonstration and stress testing.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Simulator run state."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Simulator"],"summary":"Get Status of Virtual GPS Hardware Simulator","security":[{"bearerAuth":[]}]},"post":{"description":"Launches a simulated tracker that feeds continuous realistic GPS packets along a simulated route to test live map rendering and alert rules.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Simulation started."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imei"],"properties":{"imei":{"type":"string","example":"999000000000001"},"speed":{"type":"number","default":60,"example":60},"interval_seconds":{"type":"integer","default":5,"example":5},"route":{"type":"string","enum":["dhaka_airport","chittagong_highway"],"example":"dhaka_airport"}}},"example":{"imei":"999000000000001","speed":60,"interval_seconds":5}}}},"tags":["Simulator"],"summary":"Start Virtual GPS Device Route Simulation","security":[{"bearerAuth":[]}]}},"/api/admin/simulator/{id}":{"put":{"description":"Updates and overwrites properties of the target Admin Simulator Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"example":"any"},"name":{"example":"any"},"model":{"example":"any"},"vehicle_profile":{"example":"any"},"behavior":{"example":"any"},"speed":{"example":"any"},"lat":{"example":"any"},"lon":{"example":"any"},"speed_min":{"example":"any"},"speed_max":{"example":"any"},"sensors":{"example":"any"},"route_points":{"example":"any"},"update_interval_ms":{"example":"any"},"jitter_percent":{"example":"any"},"error_mode":{"example":"any"},"connection_mode":{"example":"any"},"signal_quality":{"example":"any"}}}}}},"tags":["Simulator"],"summary":"Update Admin Simulator Id"},"delete":{"description":"Permanently removes or unlinks the target Admin Simulator Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Simulator"],"summary":"Delete Admin Simulator Id"}},"/api/admin/simulator/bulk":{"post":{"description":"Provisions, dispatches, or creates a new Admin Simulator Bulk in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"example":"any"}}}}}},"tags":["Simulator"],"summary":"Create or Trigger Admin Simulator Bulk"}},"/api/admin/simulator/bulk-create":{"post":{"description":"Provisions, dispatches, or creates a new Admin Simulator Bulk-create in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"example":"any"},"preset":{"example":"any"},"startLat":{"example":"any"},"startLon":{"example":"any"}}}}}},"tags":["Simulator"],"summary":"Create or Trigger Admin Simulator Bulk-create"}},"/api/admin/simulator/generate-route":{"post":{"description":"Provisions, dispatches, or creates a new Admin Simulator Generate-route in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"startLat":{"example":"any"},"startLon":{"example":"any"},"endLat":{"example":"any"},"endLon":{"example":"any"},"points":{"example":"any"}}}}}},"tags":["Simulator"],"summary":"Create or Trigger Admin Simulator Generate-route"}},"/api/favorites":{"get":{"description":"Retrieves a paginated list of Favorites accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Favorites"],"summary":"Get Favorites"}},"/api/favorites/ids":{"get":{"description":"Retrieves a paginated list of Favorites Ids accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Favorites"],"summary":"Get Favorites Ids"}},"/api/favorites/{imei}":{"post":{"description":"Provisions, dispatches, or creates a new Favorites Imei in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Favorites"],"summary":"Create or Trigger Favorites Imei"},"delete":{"description":"Permanently removes or unlinks the target Favorites Imei from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Favorites"],"summary":"Delete Favorites Imei"}},"/api/notification-profiles":{"get":{"description":"Retrieves a paginated list of Notification-profiles accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Profiles"],"summary":"Get Notification-profiles"},"post":{"description":"Provisions, dispatches, or creates a new Notification-profiles in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"user_ids":{"example":"any"}}}}}},"tags":["Notification Profiles"],"summary":"Create or Trigger Notification-profiles"}},"/api/notification-profiles/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Notification-profiles Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Profiles"],"summary":"Get Notification-profiles Id"},"put":{"description":"Updates and overwrites properties of the target Notification-profiles Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"user_ids":{"example":"any"}}}}}},"tags":["Notification Profiles"],"summary":"Update Notification-profiles Id"},"delete":{"description":"Permanently removes or unlinks the target Notification-profiles Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Profiles"],"summary":"Delete Notification-profiles Id"}},"/api/billing/balance":{"get":{"description":"Retrieves available prepaid coin balance, pending subscription renewals, and current coin consumption rate.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Balance and active device subscriptions count.","content":{"application/json":{"example":{"success":true,"data":{"coin_balance":1450,"active_subscriptions":42,"monthly_burn_rate":420,"days_remaining":103}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Organization Coin & Subscription Balance","security":[{"bearerAuth":[]}]}},"/api/billing/transactions":{"get":{"description":"Retrieves historical coin deposits, transfers between parent and child accounts, and monthly device renewal deductions.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Transaction history ledger."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"List Coin Balance Transaction Ledger","security":[{"bearerAuth":[]}]}},"/api/billing/transactions/export":{"get":{"description":"Retrieves a paginated list of Billing Transactions Export accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","produces":["text/csv"],"parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"},{"name":"type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Transactions Export"}},"/api/billing/settings":{"get":{"description":"Retrieves a paginated list of Billing Settings accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"org_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Settings"},"put":{"description":"Updates and overwrites properties of the target Billing Settings.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"example":"any"},"coin_validity_months":{"example":"any"},"allow_trial":{"example":"any"},"trial_duration_days":{"example":"any"},"auto_renew_on_expiry":{"example":"any"},"reset_to_inherited":{"example":"any"}}}}}},"tags":["Billing"],"summary":"Update Billing Settings"}},"/api/billing/trial-eligibility/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Billing Trial-eligibility Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Trial-eligibility Imei"}},"/api/billing/admin/orgs/{id}/balance":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Billing Admin Orgs Id Balance within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Admin Orgs Id Balance"}},"/api/billing/admin/orgs/{id}/credit":{"post":{"description":"Provisions, dispatches, or creates a new Billing Admin Orgs Id Credit in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Billing"],"summary":"Create or Trigger Billing Admin Orgs Id Credit"}},"/api/billing/admin/orgs/{id}/deduct":{"post":{"description":"Provisions, dispatches, or creates a new Billing Admin Orgs Id Deduct in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Billing"],"summary":"Create or Trigger Billing Admin Orgs Id Deduct"}},"/api/billing/admin/orgs/{id}/transactions":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Billing Admin Orgs Id Transactions within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Admin Orgs Id Transactions"}},"/api/billing/admin/transactions":{"get":{"description":"Retrieves a paginated list of Billing Admin Transactions accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Admin Transactions"}},"/api/billing/admin/run-cron":{"post":{"description":"Provisions, dispatches, or creates a new Billing Admin Run-cron in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Create or Trigger Billing Admin Run-cron"}},"/api/billing/admin/renewal-summary":{"get":{"description":"Retrieves a paginated list of Billing Admin Renewal-summary accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Admin Renewal-summary"}},"/api/billing/transfer":{"post":{"description":"Provisions, dispatches, or creates a new Billing Transfer in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"target_org_id":{"example":"any"},"amount":{"example":"any"},"idempotency_key":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Billing"],"summary":"Create or Trigger Billing Transfer"}},"/api/billing/recall":{"post":{"description":"Provisions, dispatches, or creates a new Billing Recall in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"target_org_id":{"example":"any"},"amount":{"example":"any"},"idempotency_key":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Billing"],"summary":"Create or Trigger Billing Recall"}},"/api/billing/hierarchy-balances":{"get":{"description":"Retrieves a paginated list of Billing Hierarchy-balances accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Hierarchy-balances"}},"/api/billing/admin/mint":{"post":{"description":"Provisions, dispatches, or creates a new Billing Admin Mint in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Billing"],"summary":"Create or Trigger Billing Admin Mint"}},"/api/devices/bulk/import":{"post":{"description":"Provisions hundreds or thousands of GPS tracking units in a single batch transaction. Validates IMEI checksums, assigns default fleets, models, and SIM cards, and reports validation errors row-by-row.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Batch intake summary with imported and skipped counts.","content":{"application/json":{"example":{"success":true,"data":{"imported":2,"failed":0,"errors":[]}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"402":{"description":"Payment Required"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["devices"],"properties":{"devices":{"type":"array","items":{"type":"object","required":["imei","name"],"properties":{"imei":{"type":"string","example":"864540081293581"},"name":{"type":"string","example":"Van 101"},"model":{"type":"string","example":"GT06Pro"},"plate_number":{"type":"string","example":"DHK-11-2041"},"fleet_id":{"type":"integer","example":14}}}}}},"example":{"devices":[{"imei":"864540081293581","name":"Van 101","model":"GT06Pro","plate_number":"DHK-11-2041","fleet_id":14},{"imei":"865167047241865","name":"Van 102","model":"GT06Pro","plate_number":"DHK-11-2042","fleet_id":14}]}}}},"tags":["Bulk Operations"],"summary":"Bulk Import Devices from CSV / JSON Dataset","security":[{"bearerAuth":[]}]}},"/api/devices/bulk/assign-fleet":{"post":{"description":"Transfers an array of vehicle devices to a specific fleet or sub-fleet group in one operation.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Devices assigned to fleet."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imeis","fleet_id"],"properties":{"imeis":{"type":"array","items":{"type":"string"},"example":["864540081293581","865167047241865"]},"fleet_id":{"type":"integer","example":14}}},"example":{"imeis":["864540081293581","865167047241865"],"fleet_id":14}}}},"tags":["Bulk Operations"],"summary":"Batch Assign Multiple Devices to Fleet Group","security":[{"bearerAuth":[]}]}},"/api/devices/bulk/assign-org":{"post":{"description":"Provisions, dispatches, or creates a new Devices Bulk Assign-org in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"},"org_id":{"example":"any"}}}}}},"tags":["Bulk Operations"],"summary":"Create or Trigger Devices Bulk Assign-org"}},"/api/devices/bulk/status":{"post":{"description":"Provisions, dispatches, or creates a new Devices Bulk Status in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"},"active":{"example":"any"}}}}}},"tags":["Bulk Operations"],"summary":"Create or Trigger Devices Bulk Status"}},"/api/devices/bulk/delete":{"post":{"description":"Removes an array of devices from the tenant organization in a single transaction. Historical data is archived.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Batch deletion complete."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imeis"],"properties":{"imeis":{"type":"array","items":{"type":"string"},"example":["864540081293581"]}}},"example":{"imeis":["864540081293581"]}}}},"tags":["Bulk Operations"],"summary":"Batch Delete Devices from Inventory","security":[{"bearerAuth":[]}]}},"/api/devices/bulk/templates/users":{"get":{"description":"Retrieves a paginated list of Devices Bulk Templates Users accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Operations"],"summary":"Get Devices Bulk Templates Users"}},"/api/devices/bulk/templates/devices":{"get":{"description":"Returns the formatted header structure and sample rows required for bulk CSV device intake.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"CSV file download or column specification."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Operations"],"summary":"Download Standard CSV Template for Device Import","security":[{"bearerAuth":[]}]}},"/api/bulk/import":{"post":{"description":"Provisions, dispatches, or creates a new Bulk Import in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"402":{"description":"Payment Required"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"devices":{"example":"any"}}}}}},"tags":["Bulk Operations"],"summary":"Create or Trigger Bulk Import"}},"/api/bulk/assign-fleet":{"post":{"description":"Provisions, dispatches, or creates a new Bulk Assign-fleet in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"},"fleet_id":{"example":"any"}}}}}},"tags":["Bulk Operations"],"summary":"Create or Trigger Bulk Assign-fleet"}},"/api/bulk/assign-org":{"post":{"description":"Provisions, dispatches, or creates a new Bulk Assign-org in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"},"org_id":{"example":"any"}}}}}},"tags":["Bulk Operations"],"summary":"Create or Trigger Bulk Assign-org"}},"/api/bulk/status":{"post":{"description":"Provisions, dispatches, or creates a new Bulk Status in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"},"active":{"example":"any"}}}}}},"tags":["Bulk Operations"],"summary":"Create or Trigger Bulk Status"}},"/api/bulk/delete":{"post":{"description":"Provisions, dispatches, or creates a new Bulk Delete in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"}}}}}},"tags":["Bulk Operations"],"summary":"Create or Trigger Bulk Delete"}},"/api/bulk/templates/users":{"get":{"description":"Retrieves a paginated list of Bulk Templates Users accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Operations"],"summary":"Get Bulk Templates Users"}},"/api/bulk/templates/devices":{"get":{"description":"Retrieves a paginated list of Bulk Templates Devices accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Operations"],"summary":"Get Bulk Templates Devices"}},"/api/admin/security/access-logs":{"get":{"description":"Retrieves a paginated list of Admin Security Access-logs accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"user_id","in":"query","schema":{"type":"string"}},{"name":"event_type","in":"query","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Get Admin Security Access-logs"}},"/api/admin/security/api-logs":{"get":{"description":"Retrieves a paginated list of Admin Security Api-logs accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"org_id","in":"query","schema":{"type":"string"}},{"name":"method","in":"query","schema":{"type":"string"}},{"name":"path","in":"query","schema":{"type":"string"}},{"name":"user_id","in":"query","schema":{"type":"string"}},{"name":"entity_type","in":"query","schema":{"type":"string"}},{"name":"mutations_only","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string","example":"Toyota"},"description":"Search filter keyword"},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Get Admin Security Api-logs"}},"/api/admin/security/device-audit-logs":{"get":{"description":"Retrieves a paginated list of Admin Security Device-audit-logs accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"org_id","in":"query","schema":{"type":"string"}},{"name":"device_imei","in":"query","schema":{"type":"string"}},{"name":"user_id","in":"query","schema":{"type":"string"}},{"name":"action","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string","example":"Toyota"},"description":"Search filter keyword"},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Get Admin Security Device-audit-logs"}},"/api/admin/security/command-logs":{"get":{"description":"Retrieves a paginated list of Admin Security Command-logs accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"org_id","in":"query","schema":{"type":"string"}},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"user_id","in":"query","schema":{"type":"string"}},{"name":"command_type","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"channel","in":"query","schema":{"type":"string","example":1},"description":"Camera video channel number (1-8)"},{"name":"search","in":"query","schema":{"type":"string","example":"Toyota"},"description":"Search filter keyword"},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Get Admin Security Command-logs"}},"/api/admin/security/export":{"get":{"description":"Retrieves a paginated list of Admin Security Export accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","produces":["text/csv; charset=utf-8"],"parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"org_id","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string","example":"Toyota"},"description":"Search filter keyword"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Get Admin Security Export"}},"/api/admin/security/api-analytics":{"get":{"description":"Retrieves a paginated list of Admin Security Api-analytics accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"days","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Get Admin Security Api-analytics"}},"/api/admin/security/sessions":{"get":{"description":"Retrieves a paginated list of Admin Security Sessions accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Get Admin Security Sessions"}},"/api/admin/security/sessions/{id}":{"delete":{"description":"Permanently removes or unlinks the target Admin Security Sessions Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Delete Admin Security Sessions Id"}},"/api/admin/ip-management/blocked":{"get":{"description":"Retrieves a paginated list of Admin Ip-management Blocked accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["IP Management"],"summary":"Get Admin Ip-management Blocked"}},"/api/admin/ip-management/unblock":{"post":{"description":"Provisions, dispatches, or creates a new Admin Ip-management Unblock in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ip":{"example":"any"},"type":{"example":"any"}}}}}},"tags":["IP Management"],"summary":"Create or Trigger Admin Ip-management Unblock"}},"/api/admin/ip-management/blacklist":{"get":{"description":"Retrieves a paginated list of Admin Ip-management Blacklist accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["IP Management"],"summary":"Get Admin Ip-management Blacklist"},"post":{"description":"Provisions, dispatches, or creates a new Admin Ip-management Blacklist in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ip":{"example":"any"},"reason":{"example":"any"}}}}}},"tags":["IP Management"],"summary":"Create or Trigger Admin Ip-management Blacklist"}},"/api/admin/ip-management/blacklist/{ip}":{"delete":{"description":"Permanently removes or unlinks the target Admin Ip-management Blacklist Ip from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"ip","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["IP Management"],"summary":"Delete Admin Ip-management Blacklist Ip"}},"/api/admin/system-stats":{"get":{"description":"Retrieves a paginated list of Admin System-stats accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Admin Diagnostics"],"summary":"Get Admin System-stats"}},"/api/roles/permissions":{"get":{"description":"Retrieves a paginated list of Roles Permissions accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Roles"],"summary":"Get Roles Permissions"}},"/api/roles/templates":{"get":{"description":"Retrieves a paginated list of Roles Templates accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Roles"],"summary":"Get Roles Templates"}},"/api/roles":{"get":{"description":"Retrieves standard system roles (Platform Admin, Admin, Manager, Viewer, Driver) and custom tenant roles with granular permission scopes.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of roles and permission matrices."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Roles"],"summary":"List Available RBAC Roles & Permissions","security":[{"bearerAuth":[]}]},"post":{"description":"Creates a customized role specifying exact permissions for devices, tracking, alerts, geofences, commands, reports, and billing.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Custom role created."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"permissions":{"example":"any"},"template":{"example":"any"}}}}}},"tags":["Roles"],"summary":"Create Custom Role with Granular Permissions","security":[{"bearerAuth":[]}]}},"/api/roles/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Roles Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Roles"],"summary":"Get Roles Id"},"put":{"description":"Updates and overwrites properties of the target Roles Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"permissions":{"example":"any"}}}}}},"tags":["Roles"],"summary":"Update Roles Id"},"delete":{"description":"Permanently removes or unlinks the target Roles Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Roles"],"summary":"Delete Roles Id"}},"/api/roles/{id}/assign":{"post":{"description":"Provisions, dispatches, or creates a new Roles Id Assign in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userIds":{"example":"any"}}}}}},"tags":["Roles"],"summary":"Create or Trigger Roles Id Assign"}},"/api/roles/{id}/unassign":{"post":{"description":"Provisions, dispatches, or creates a new Roles Id Unassign in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userIds":{"example":"any"}}}}}},"tags":["Roles"],"summary":"Create or Trigger Roles Id Unassign"}},"/api/settings/public":{"get":{"description":"Retrieves a paginated list of Settings Public accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Settings"],"summary":"Get Settings Public"}},"/api/settings/status-thresholds":{"get":{"description":"Retrieves a paginated list of Settings Status-thresholds accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Settings"],"summary":"Get Settings Status-thresholds"},"put":{"description":"Updates and overwrites properties of the target Settings Status-thresholds.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"min_moving_speed_kmh":{"example":"any"},"online_timeout_minutes":{"example":"any"},"min_trip_duration_seconds":{"example":"any"},"min_parking_duration_seconds":{"example":"any"},"ignition_debounce_seconds":{"example":"any"}}}}}},"tags":["Settings"],"summary":"Update Settings Status-thresholds"}},"/api/settings":{"get":{"description":"Retrieves a paginated list of Settings accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Settings"],"summary":"Get Settings"}},"/api/settings/{key}":{"put":{"description":"Updates and overwrites properties of the target Settings Key.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"battery_level"},"description":"Attribute or preference setting key"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"example":"any"}}}}}},"tags":["Settings"],"summary":"Update Settings Key"}},"/api/payments/plans":{"get":{"description":"Retrieves a paginated list of Payments Plans accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Payments"],"summary":"Get Payments Plans"}},"/api/payments/collect-cash":{"post":{"description":"Provisions, dispatches, or creates a new Payments Collect-cash in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"example":"any"},"plan_id":{"example":"any"},"amount":{"example":"any"},"coins":{"example":"any"},"currency":{"example":"any"},"payment_method":{"example":"any"},"reference":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Payments"],"summary":"Create or Trigger Payments Collect-cash"}},"/api/payments/history":{"get":{"description":"Retrieves a paginated list of Payments History accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Payments"],"summary":"Get Payments History"}},"/api/payments/subscription":{"get":{"description":"Retrieves a paginated list of Payments Subscription accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Payments"],"summary":"Get Payments Subscription"}},"/api/payments/admin/plans":{"post":{"description":"Provisions, dispatches, or creates a new Payments Admin Plans in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"price":{"example":"any"},"currency":{"example":"any"},"interval":{"example":"any"},"device_limit":{"example":"any"},"coin_value":{"example":"any"},"features":{"example":"any"},"is_default":{"example":"any"},"sort_order":{"example":"any"},"org_id":{"example":"any"}}}}}},"tags":["Payments"],"summary":"Create or Trigger Payments Admin Plans"}},"/api/payments/admin/plans/{id}":{"put":{"description":"Updates and overwrites properties of the target Payments Admin Plans Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"price":{"example":"any"},"currency":{"example":"any"},"interval":{"example":"any"},"device_limit":{"example":"any"},"coin_value":{"example":"any"},"features":{"example":"any"},"is_default":{"example":"any"},"active":{"example":"any"},"sort_order":{"example":"any"}}}}}},"tags":["Payments"],"summary":"Update Payments Admin Plans Id"},"delete":{"description":"Permanently removes or unlinks the target Payments Admin Plans Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Payments"],"summary":"Delete Payments Admin Plans Id"}},"/api/payments/admin/revenue":{"get":{"description":"Retrieves a paginated list of Payments Admin Revenue accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Payments"],"summary":"Get Payments Admin Revenue"}},"/api/payments/admin/transactions":{"get":{"description":"Retrieves a paginated list of Payments Admin Transactions accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"gateway","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Payments"],"summary":"Get Payments Admin Transactions"}},"/api/custom-fields":{"get":{"description":"Retrieves extensible custom fields configured for entities (Vehicles, Users, Fleets, Drivers) such as Insurance Policy Number, Vehicle Color, or Road Tax Expiry.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"entity_type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of custom field definitions."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Custom Fields"],"summary":"List Dynamic Custom Schema Fields","security":[{"bearerAuth":[]}]},"post":{"description":"Creates an extra schema attribute on an entity type with validation constraints (text, number, date, dropdown).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Custom field registered."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["field_name","entity_type","field_type"],"properties":{"field_name":{"type":"string","description":"Internal field identifier (or pass as \"name\")","example":"fitness_cert_expiry"},"name":{"type":"string","description":"Alias for field_name","example":"fitness_cert_expiry"},"field_label":{"type":"string","description":"User-facing label","example":"Fitness Certificate Expiry"},"entity_type":{"type":"string","enum":["device","driver","fleet","user","geofence"],"example":"device"},"field_type":{"type":"string","enum":["text","number","date","select","boolean"],"description":"Data type (or pass as \"data_type\")","example":"date"},"data_type":{"type":"string","enum":["text","number","date","select","boolean"],"description":"Alias for field_type","example":"date"},"options":{"type":"array","items":{"type":"string"},"description":"Dropdown options if field_type is select","example":["Option A","Option B"]},"is_required":{"type":"boolean","default":false,"example":false}}},"example":{"field_name":"fitness_cert_expiry","field_label":"Fitness Certificate Expiry","entity_type":"device","field_type":"date","is_required":false}}}},"tags":["Custom Fields"],"summary":"Define New Dynamic Custom Field","security":[{"bearerAuth":[]}]}},"/api/custom-fields/search":{"get":{"description":"Retrieves a paginated list of Custom-fields Search accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"entity_type","in":"query","schema":{"type":"string"}},{"name":"field_id","in":"query","schema":{"type":"string"}},{"name":"value","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Custom Fields"],"summary":"Get Custom-fields Search"}},"/api/custom-fields/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Custom-fields Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Custom Fields"],"summary":"Get Custom-fields Id"},"put":{"description":"Updates and overwrites properties of the target Custom-fields Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"field_name":{"example":"any"},"field_type":{"example":"any"},"options":{"example":"any"},"required":{"example":"any"},"sort_order":{"example":"any"}}}}}},"tags":["Custom Fields"],"summary":"Update Custom-fields Id"},"delete":{"description":"Permanently removes or unlinks the target Custom-fields Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Custom Fields"],"summary":"Delete Custom-fields Id"}},"/api/custom-fields/reorder":{"put":{"description":"Updates and overwrites properties of the target Custom-fields Reorder.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"field_orders":{"example":"any"}}}}}},"tags":["Custom Fields"],"summary":"Update Custom-fields Reorder"}},"/api/custom-fields/values/{entity_type}/bulk":{"get":{"description":"Retrieves a paginated list of Custom-fields Values Entity_type Bulk accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"entity_type","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"entity_ids","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Custom Fields"],"summary":"Get Custom-fields Values Entity_type Bulk"}},"/api/custom-fields/values/{entity_type}/{entity_id}":{"get":{"description":"Retrieves a paginated list of Custom-fields Values Entity_type Entity_id accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"entity_type","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Custom Fields"],"summary":"Get Custom-fields Values Entity_type Entity_id"},"put":{"description":"Updates and overwrites properties of the target Custom-fields Values Entity_type Entity_id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"entity_type","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"values":{"example":"any"}}}}}},"tags":["Custom Fields"],"summary":"Update Custom-fields Values Entity_type Entity_id"}},"/api/notification-templates":{"get":{"description":"Retrieves predefined message templates used across Email, SMS, WhatsApp, and FCM Push with dynamic variables (e.g. {{vehicle_name}}, {{speed}}, {{address}}).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"channel","in":"query","schema":{"type":"string","example":1},"description":"Camera video channel number (1-8)"}],"responses":{"200":{"description":"List of notification templates."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Templates"],"summary":"List Multi-Channel Notification Templates","security":[{"bearerAuth":[]}]},"post":{"description":"Creates a new customizable message template for specific alert triggers (e.g. overspeed, geofence_enter, geofence_exit, sos, fuel_theft).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Notification template created."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channel","event_type","body"],"properties":{"channel":{"type":"string","enum":["email","sms","push"],"description":"Notification delivery channel","example":"sms"},"event_type":{"type":"string","enum":["overspeed","geofence_enter","geofence_exit","sos","offline","fuel_theft","deviceMoving","deviceStopped","deviceEngineIdle","route_deviation","default"],"description":"Trigger event type","example":"overspeed"},"name":{"type":"string","description":"Template display name (alias for event_type if event_type is omitted)","example":"Overspeed SMS Template"},"subject":{"type":"string","description":"Email/Push subject heading","example":"Speed Alert: {{device_name}}"},"body":{"type":"string","description":"Template message body supporting dynamic variables","example":"Alert: {{device_name}} exceeded {{speed_limit}} km/h at {{location}}."}}},"example":{"channel":"sms","event_type":"overspeed","body":"Alert: {{device_name}} exceeded {{speed_limit}} km/h at {{location}}."}}}},"tags":["Notification Templates"],"summary":"Create Notification Message Template","security":[{"bearerAuth":[]}]}},"/api/notification-templates/variables":{"get":{"description":"Retrieves a paginated list of Notification-templates Variables accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Templates"],"summary":"Get Notification-templates Variables"}},"/api/notification-templates/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Notification-templates Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Templates"],"summary":"Get Notification-templates Id"},"put":{"description":"Updates and overwrites properties of the target Notification-templates Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"example":"any"},"body":{"example":"any"},"active":{"example":"any"}}}}}},"tags":["Notification Templates"],"summary":"Update Notification-templates Id"},"delete":{"description":"Permanently removes or unlinks the target Notification-templates Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Templates"],"summary":"Delete Notification-templates Id"}},"/api/notification-templates/preview":{"post":{"description":"Provisions, dispatches, or creates a new Notification-templates Preview in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"example":"any"},"body":{"example":"any"},"event_type":{"example":"any"}}}}}},"tags":["Notification Templates"],"summary":"Create or Trigger Notification-templates Preview"}},"/api/notification-templates/{id}/reset":{"post":{"description":"Provisions, dispatches, or creates a new Notification-templates Id Reset in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Templates"],"summary":"Create or Trigger Notification-templates Id Reset"}},"/api/domains":{"get":{"description":"Retrieves custom domains onboarded for white-label branding, including SSL/TLS certificate status and DNS CNAME verification.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of custom domains."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Domains"],"summary":"List Custom White-Label CNAME Domains","security":[{"bearerAuth":[]}]},"post":{"description":"Provisions a new custom tracking domain (e.g. `gps.xeekar.com`) and initiates automated Caddy Let's Encrypt SSL/TLS verification.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"201":{"description":"Domain added; DNS CNAME target returned."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","example":"gps.xeekar.com"}}},"example":{"domain":"gps.xeekar.com"}}}},"tags":["Domains"],"summary":"Add Custom Domain for White-Label Access","security":[{"bearerAuth":[]}]},"delete":{"description":"Permanently removes or unlinks the target Domains from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Domains"],"summary":"Delete Domains"}},"/api/domains/verify":{"post":{"description":"Provisions, dispatches, or creates a new Domains Verify in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Domains"],"summary":"Create or Trigger Domains Verify"}},"/api/domains/check-dns":{"post":{"description":"Provisions, dispatches, or creates a new Domains Check-dns in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"host":{"example":"any"},"expectedType":{"example":"any"},"recordHost":{"example":"any"}}}}}},"tags":["Domains"],"summary":"Create or Trigger Domains Check-dns"}},"/api/domains/check-all-dns":{"post":{"description":"Provisions, dispatches, or creates a new Domains Check-all-dns in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Domains"],"summary":"Create or Trigger Domains Check-all-dns"}},"/api/chat/rooms":{"get":{"description":"Retrieves a paginated list of Chat Rooms accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Chat"],"summary":"Get Chat Rooms"}},"/api/chat/rooms/{roomId}/messages":{"get":{"description":"Retrieves a paginated list of Chat Rooms RoomId Messages accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string","example":"room-14-dispatch"},"description":"Chat conversation room identifier"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Chat"],"summary":"Get Chat Rooms RoomId Messages"},"post":{"description":"Provisions, dispatches, or creates a new Chat Rooms RoomId Messages in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string","example":"room-14-dispatch"},"description":"Chat conversation room identifier"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"example":"any"},"receiverId":{"example":"any"}}}}}},"tags":["Chat"],"summary":"Create or Trigger Chat Rooms RoomId Messages"}},"/api/notifications":{"get":{"description":"Retrieves in-app notification center inbox for the authenticated user, including read status, timestamp, and alert payload.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"unread","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of in-app notifications."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notifications"],"summary":"List User In-App Notifications & Alerts Inbox","security":[{"bearerAuth":[]}]}},"/api/notifications/unread-count":{"get":{"description":"Returns the count of unread alert notifications to display on the dashboard bell badge.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Unread notification count.","content":{"application/json":{"example":{"count":3}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notifications"],"summary":"Get Count of Unread Notifications","security":[{"bearerAuth":[]}]}},"/api/notifications/read-all":{"put":{"description":"Clears unread indicators by marking all notification inbox messages as read for the user.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"All notifications marked as read."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"example":"any"}}}}}},"tags":["Notifications"],"summary":"Mark All Notifications as Read","security":[{"bearerAuth":[]}]}},"/api/notifications/{id}/read":{"put":{"description":"Updates and overwrites properties of the target Notifications Id Read.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notifications"],"summary":"Update Notifications Id Read"}},"/api/notifications/batch":{"delete":{"description":"Permanently removes or unlinks the target Notifications Batch from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"example":"any"},"all":{"example":"any"},"category":{"example":"any"}}}}}},"tags":["Notifications"],"summary":"Delete Notifications Batch"}},"/api/notifications/batch-delete":{"post":{"description":"Provisions, dispatches, or creates a new Notifications Batch-delete in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"example":"any"},"all":{"example":"any"},"category":{"example":"any"}}}}}},"tags":["Notifications"],"summary":"Create or Trigger Notifications Batch-delete"}},"/api/notifications/{id}":{"delete":{"description":"Permanently removes or unlinks the target Notifications Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notifications"],"summary":"Delete Notifications Id"}},"/api/inspections/templates":{"get":{"description":"Retrieves a paginated list of Inspections Templates accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Inspections"],"summary":"Get Inspections Templates"},"post":{"description":"Provisions, dispatches, or creates a new Inspections Templates in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"type":{"example":"any"},"items":{"example":"any"}}}}}},"tags":["Inspections"],"summary":"Create or Trigger Inspections Templates"}},"/api/inspections/templates/{id}":{"put":{"description":"Updates and overwrites properties of the target Inspections Templates Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"type":{"example":"any"},"active":{"example":"any"},"items":{"example":"any"}}}}}},"tags":["Inspections"],"summary":"Update Inspections Templates Id"},"delete":{"description":"Permanently removes or unlinks the target Inspections Templates Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Inspections"],"summary":"Delete Inspections Templates Id"}},"/api/inspections/stats":{"get":{"description":"Retrieves a paginated list of Inspections Stats accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Inspections"],"summary":"Get Inspections Stats"}},"/api/inspections":{"get":{"description":"Retrieves driver vehicle inspection reports (DVIR checklists) covering tire condition, lights, brakes, windshield, fluid levels, and reported defects.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"template_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of inspection checklist submissions."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Inspections"],"summary":"List Pre-Trip & Post-Trip Vehicle Inspections (DVIR)","security":[{"bearerAuth":[]}]},"post":{"description":"Submits an electronic inspection report completed by the driver prior to departure or after shift completion.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Inspection recorded successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_id"],"properties":{"device_id":{"type":"string","description":"Device IMEI (or pass as imei)","example":"864540081293581"},"imei":{"type":"string","description":"Alias for device_id","example":"864540081293581"},"template_id":{"type":"string","format":"uuid","description":"Checklist template UUID (optional, defaults to org template)","example":"550e8400-e29b-41d4-a716-446655440000"},"passed":{"type":"boolean","description":"Quick pass/fail overall indicator","example":true},"odometer":{"type":"number","example":18450},"responses":{"type":"array","description":"Detailed checklist question responses","items":{"type":"object","required":["result"],"properties":{"item_id":{"type":"string","format":"uuid","description":"Item UUID"},"result":{"type":"string","enum":["pass","fail","na"],"example":"pass"},"notes":{"type":"string","example":"Good"}}}},"items":{"type":"object","description":"Key-value map of items (convenience alias for responses)","example":{"brakes":"pass","tires":"pass","lights":"pass","horn":"pass"}},"notes":{"type":"string","example":"Pre-trip check complete"}}},"example":{"imei":"864540081293581","passed":true,"odometer":18450,"items":{"brakes":"pass","tires":"pass"}}}}},"tags":["Inspections"],"summary":"Submit Vehicle Inspection Checklist (DVIR)","security":[{"bearerAuth":[]}]}},"/api/inspections/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Inspections Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Inspections"],"summary":"Get Inspections Id"}},"/api/expenses":{"get":{"description":"Retrieves vehicle expenses (fuel purchase, toll fees, parking, traffic fines, maintenance) with receipt image URLs and category totals.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"device_imei","in":"query","schema":{"type":"string"}},{"name":"imei","in":"query","schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"date_from","in":"query","schema":{"type":"string"}},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"},{"name":"date_to","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string","example":"Toyota"},"description":"Search filter keyword"}],"responses":{"200":{"description":"List of recorded expenses."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Expenses"],"summary":"List Fleet Operational Expenses & Fuel Receipts","security":[{"bearerAuth":[]}]},"post":{"description":"Logs an expenditure incurred by a vehicle or driver during commercial operations.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Expense saved."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["category","amount"],"properties":{"device_id":{"type":"string","description":"Vehicle device IMEI (or pass as imei)","example":"864540081293581"},"imei":{"type":"string","description":"Alias for device_id","example":"864540081293581"},"category":{"type":"string","enum":["fuel","toll","parking","maintenance","fine","other"],"example":"toll"},"amount":{"type":"number","example":350},"currency":{"type":"string","default":"BDT","example":"BDT"},"notes":{"type":"string","example":"Padma Bridge Toll"}}},"example":{"imei":"864540081293581","category":"toll","amount":350,"notes":"Padma Bridge Toll"}}}},"tags":["Expenses"],"summary":"Record Vehicle Expense Entry","security":[{"bearerAuth":[]}]}},"/api/expenses/summary":{"get":{"description":"Retrieves a paginated list of Expenses Summary accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"date_from","in":"query","schema":{"type":"string"}},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"},{"name":"date_to","in":"query","schema":{"type":"string"}},{"name":"device_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Expenses"],"summary":"Get Expenses Summary"}},"/api/expenses/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Expenses Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Expenses"],"summary":"Get Expenses Id"},"put":{"description":"Updates and overwrites properties of the target Expenses Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_id":{"example":"any"},"device_imei":{"example":"any"},"type":{"example":"any"},"category":{"example":"any"},"amount":{"example":"any"},"liters":{"example":"any"},"currency":{"example":"any"},"date":{"example":"any"},"description":{"example":"any"},"notes":{"example":"any"},"receipt_url":{"example":"any"},"receipt_attachment":{"example":"any"},"payment_method":{"example":"any"},"vendor":{"example":"any"},"reference_number":{"example":"any"},"odometer":{"example":"any"}}}}}},"tags":["Expenses"],"summary":"Update Expenses Id"},"patch":{"description":"Applies partial field modifications to the target Expenses Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_id":{"example":"any"},"device_imei":{"example":"any"},"type":{"example":"any"},"category":{"example":"any"},"amount":{"example":"any"},"liters":{"example":"any"},"currency":{"example":"any"},"date":{"example":"any"},"description":{"example":"any"},"notes":{"example":"any"},"receipt_url":{"example":"any"},"receipt_attachment":{"example":"any"},"payment_method":{"example":"any"},"vendor":{"example":"any"},"reference_number":{"example":"any"},"odometer":{"example":"any"}}}}}},"tags":["Expenses"],"summary":"Modify Expenses Id"},"delete":{"description":"Permanently removes or unlinks the target Expenses Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Expenses"],"summary":"Delete Expenses Id"}},"/api/expenses/analyze-receipt":{"post":{"description":"Provisions, dispatches, or creates a new Expenses Analyze-receipt in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"422":{"description":"Unprocessable Entity"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"example":"any"},"image_base64":{"example":"any"},"image_url":{"example":"any"}}}}}},"tags":["Expenses"],"summary":"Create or Trigger Expenses Analyze-receipt"}},"/api/bulk-tanks":{"get":{"description":"Retrieves inventory of stationary depot fuel tanks, including current fuel volume, capacity, calibrated sensor port, and fuel type (Diesel, Petrol, Octane, Jet-A1).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of bulk tanks and current fuel stocks.","content":{"application/json":{"example":{"success":true,"data":[{"id":"tank-01","name":"Depot Yard Diesel Tank A","fuel_type":"diesel","capacity_liters":25000,"current_volume_liters":18450,"percent_full":73.8,"sensor_imei":"865167047241865"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Fuel Tanks"],"summary":"List Yard Bulk Fuel Tanks & Stationary Storage","security":[{"bearerAuth":[]}]},"post":{"description":"Adds a stationary depot bulk tank with calibrated tank dimensions and optional IoT level sensor probe.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Bulk tank created successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","capacity_liters","fuel_type"],"properties":{"name":{"type":"string","example":"Depot Yard Diesel Tank B"},"capacity_liters":{"type":"number","example":30000},"fuel_type":{"type":"string","enum":["diesel","petrol","octane","cng","lpg"],"example":"diesel"},"sensor_imei":{"type":"string","example":"865167047241865"}}},"example":{"name":"Depot Yard Diesel Tank B","capacity_liters":30000,"fuel_type":"diesel"}}}},"tags":["Bulk Fuel Tanks"],"summary":"Register New Yard Bulk Fuel Tank","security":[{"bearerAuth":[]}]}},"/api/bulk-tanks/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Bulk-tanks Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Fuel Tanks"],"summary":"Get Bulk-tanks Id"},"put":{"description":"Updates and overwrites properties of the target Bulk-tanks Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"location":{"example":"any"},"fuel_type":{"example":"any"},"capacity_liters":{"example":"any"},"current_liters":{"example":"any"},"alert_low_liters":{"example":"any"},"dipstick_calibration":{"example":"any"}}}}}},"tags":["Bulk Fuel Tanks"],"summary":"Update Bulk-tanks Id"},"delete":{"description":"Permanently removes or unlinks the target Bulk-tanks Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Fuel Tanks"],"summary":"Delete Bulk-tanks Id"}},"/api/bulk-tanks/{id}/logs":{"get":{"description":"Retrieves delivery intake logs (tanker refill) and vehicle dispensation transactions from this stationary tank.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"tank-01"},"description":"Bulk tank ID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"Dispensation and intake logs."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Fuel Tanks"],"summary":"Get Bulk Tank Fuel Intake & Dispensation Ledger","security":[{"bearerAuth":[]}]},"post":{"description":"Records a fuel dispensation to a specific fleet vehicle or intake delivery from an oil marketing company.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"tank-01"},"description":"Bulk tank ID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Fuel transaction logged."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["transaction_type","liters"],"properties":{"transaction_type":{"type":"string","enum":["dispense","refill"],"example":"dispense"},"liters":{"type":"number","example":120},"vehicle_imei":{"type":"string","example":"864540081293581"},"driver_name":{"type":"string","example":"Rahim Khan"},"cost_per_liter":{"type":"number","example":105}}},"example":{"transaction_type":"dispense","liters":120,"vehicle_imei":"864540081293581","driver_name":"Rahim Khan"}}}},"tags":["Bulk Fuel Tanks"],"summary":"Record Fuel Dispensation or Refill Log","security":[{"bearerAuth":[]}]}},"/api/weather":{"get":{"description":"Fetches real-time ambient weather (temperature, humidity, precipitation, wind speed, visibility) for vehicle latitude and longitude coordinates.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"lat","in":"query","schema":{"type":"number","example":23.8103},"required":true,"description":"Latitude coordinate"},{"name":"lon","in":"query","schema":{"type":"number","example":90.4125},"required":true,"description":"Longitude coordinate"}],"responses":{"200":{"description":"Live atmospheric conditions.","content":{"application/json":{"example":{"temp_c":29.5,"condition":"Partly Cloudy","humidity":72,"wind_kph":14.2}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"502":{"description":"Bad Gateway"},"503":{"description":"Service Unavailable"}},"tags":["Weather"],"summary":"Get Live Weather & Atmospheric Conditions for Coordinates","security":[{"bearerAuth":[]}]}},"/api/fuel-prices/nearest":{"get":{"description":"Retrieves current retail prices per liter for Diesel, Octane, Petrol, and CNG for fleet fuel cost calculation based on latitude and longitude coordinates (defaults to Dhaka if omitted).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"lat","in":"query","schema":{"type":"number","example":23.8103},"description":"Vehicle latitude (defaults to 23.8103)"},{"name":"lon","in":"query","schema":{"type":"number","example":90.4125},"description":"Vehicle longitude (defaults to 90.4125)"}],"responses":{"200":{"description":"Current fuel prices per liter.","content":{"application/json":{"example":{"success":true,"data":{"city":"Dhaka","state":"Dhaka","petrol":125,"diesel":105,"cng":43,"octane":130,"lpg":100,"date":"2026-10-11"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fuel Prices"],"summary":"Get Current Government / Market Fuel Prices Near Location","security":[{"bearerAuth":[]}]}},"/api/fuel-prices":{"get":{"description":"Retrieves current retail prices per liter for Diesel, Octane, Petrol, and CNG for fleet fuel cost calculation (defaults to capital / base city).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"lat","in":"query","schema":{"type":"number","example":23.8103},"description":"Vehicle latitude (defaults to 23.8103)"},{"name":"lon","in":"query","schema":{"type":"number","example":90.4125},"description":"Vehicle longitude (defaults to 90.4125)"}],"responses":{"200":{"description":"Current fuel prices per liter.","content":{"application/json":{"example":{"success":true,"data":{"city":"Dhaka","state":"Dhaka","petrol":125,"diesel":105,"cng":43,"octane":130,"lpg":100,"date":"2026-10-11"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fuel Prices"],"summary":"Get Current Government / Market Fuel Prices","security":[{"bearerAuth":[]}]}},"/api/ai/query":{"post":{"description":"Ask natural language questions about your fleet (e.g. \"Which vehicle drove the most kilometers this week?\", \"Did any vehicle leave Dhaka after 10 PM?\", \"Show top 3 fuel consumers\"). The AI agent converts the prompt into SQL/analytics queries and returns structured data and insights.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"AI-generated fleet answer with underlying telematics data.","content":{"application/json":{"example":{"answer":"Toyota Allion 2024 (DHK-METRO-GA-11-2041) drove 184.2 km today between 08:15 AM and 04:30 PM.","data":[{"imei":"864540081293581","distance_km":184.2}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","example":"Which vehicle drove the most distance today?"}}},"example":{"prompt":"Which vehicle drove the most distance today?"}}}},"tags":["AI Assistant"],"summary":"Query Fleet Telematics via Natural Language AI Copilot","security":[{"bearerAuth":[]}]}},"/api/ai/presets":{"get":{"description":"Retrieves a paginated list of Ai Presets accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["AI Assistant"],"summary":"Get Ai Presets"}},"/api/ai/models":{"get":{"description":"Retrieves a paginated list of Ai Models accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["AI Assistant"],"summary":"Get Ai Models"}},"/api/ai/health":{"get":{"description":"Retrieves a paginated list of Ai Health accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["AI Assistant"],"summary":"Get Ai Health"}},"/api/certificates/generate":{"post":{"description":"Creates an official government/regulatory compliance certificate for a vehicle verifying that a certified AIS-140 / GPS tracker and emergency panic button are professionally installed.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Certificate generated with downloadable PDF URL."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imei"],"properties":{"imei":{"type":"string","example":"864540081293581"},"technician_name":{"type":"string","example":"Md. Kabir Hossain"},"certification_authority":{"type":"string","example":"BRTA Compliant VTS"}}},"example":{"imei":"864540081293581","technician_name":"Md. Kabir Hossain"}}}},"tags":["Certificates"],"summary":"Generate Official GPS Tracker Installation Certificate (PDF)","security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/recordings":{"get":{"description":"Retrieves audio recordings and media uploaded from devices via 0x8D or HTTP upload.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"List of device recordings."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"List Audio / Video Recordings Uploaded for Device","security":[{"bearerAuth":[]}]}},"/api/recordings/{id}/download":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Recordings Id Download within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"Get Recordings Id Download"}},"/api/recordings/{id}":{"delete":{"description":"Permanently removes or unlinks the target Recordings Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"Delete Recordings Id"}},"/api/devices/{imei}/alarm-attachments":{"get":{"description":"Retrieves photo snapshots and video clips captured automatically during harsh braking, crash collision, driver distraction (DMS), or forward collision warning (FCW).","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"List of alarm attachments with presigned thumbnail and video URLs."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"List Dashcam Alarm Snapshots & Video Evidence","security":[{"bearerAuth":[]}]}},"/api/alarm-attachments/{id}/download":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Alarm-attachments Id Download within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"Get Alarm-attachments Id Download"}},"/api/alarm-attachments/{id}":{"delete":{"description":"Permanently removes or unlinks the target Alarm-attachments Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"Delete Alarm-attachments Id"}},"/api/video/health/summary":{"get":{"summary":"Get video health summary metrics","description":"Retrieves aggregate health counts: total cameras, recording ok, warnings, faults, offline.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/health":{"get":{"summary":"List video device health status","description":"Lists video-configured devices with SD card status, recording state, storage %, active alerts.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"fleet_id","in":"query","schema":{"type":"string","example":14},"description":"Fleet or subgroup numerical identifier"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/health/{imei}":{"get":{"summary":"Get single device video health","description":"Retrieves current video health and recent 50 audit log entries for a device.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/health/{imei}/acknowledge":{"post":{"summary":"Acknowledge video fault","description":"Marks an active video fault as acknowledged by a manager.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"example":"any"}}}}}},"tags":["Video Telematics"]}},"/api/video/health/{imei}/resolve":{"post":{"summary":"Resolve video fault","description":"Marks a video fault as resolved and resets recording status.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"example":"any"}}}}}},"tags":["Video Telematics"]}},"/api/video/health/{imei}/enable-snippets":{"post":{"summary":"Re-enable snippet capture","description":"Re-enables automated snippet capture for a device after consecutive failures.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/events/summary":{"get":{"summary":"Get event video inbox summary counts","description":"Retrieves total unreviewed, critical, high, reviewed, coached, and dismissed counts.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/events":{"get":{"summary":"Query Event Video Inbox","description":"Retrieves video event clips with filters by event_type, severity, review_status, imei, driver_id, dates.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"event_type","in":"query","schema":{"type":"string"}},{"name":"severity","in":"query","schema":{"type":"string"}},{"name":"review_status","in":"query","schema":{"type":"string"}},{"name":"imei","in":"query","schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"driver_id","in":"query","schema":{"type":"string"}},{"name":"date_from","in":"query","schema":{"type":"string"}},{"name":"date_to","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/events/{id}":{"get":{"summary":"Get single event video detail","description":"Retrieves event details, telemetry overlay, driver, and review information.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/events/{id}/review":{"patch":{"summary":"Review video event clip","description":"Updates review status (reviewed, coached, dismissed) and manager notes.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Video Telematics"]}},"/api/trailers":{"get":{"description":"Retrieves trailer chassis inventory with current hitching status and paired prime mover / tractor truck.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of trailers."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trailers"],"summary":"List Commercial Trailers & Detachable Assets","security":[{"bearerAuth":[]}]},"post":{"description":"Adds a new trailer chassis, flatbed, or reefer box to the fleet.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Trailer created."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"plate_number":{"example":"any"},"trailer_type":{"example":"any"},"rfid_tag":{"example":"any"},"ble_uuid":{"example":"any"},"cargo_capacity_kg":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Trailers"],"summary":"Register New Trailer Asset","security":[{"bearerAuth":[]}]}},"/api/trailers/{id}":{"put":{"description":"Updates and overwrites properties of the target Trailers Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"plate_number":{"example":"any"},"trailer_type":{"example":"any"},"rfid_tag":{"example":"any"},"ble_uuid":{"example":"any"},"cargo_capacity_kg":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Trailers"],"summary":"Update Trailers Id"},"delete":{"description":"Permanently removes or unlinks the target Trailers Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trailers"],"summary":"Delete Trailers Id"}},"/api/trailers/{id}/hitch":{"post":{"description":"Provisions, dispatches, or creates a new Trailers Id Hitch in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_imei":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Trailers"],"summary":"Create or Trigger Trailers Id Hitch"}},"/api/trailers/{id}/unhitch":{"post":{"description":"Provisions, dispatches, or creates a new Trailers Id Unhitch in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trailers"],"summary":"Create or Trigger Trailers Id Unhitch"}},"/api/trailers/{id}/history":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Trailers Id History within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trailers"],"summary":"Get Trailers Id History"}},"/api/video/{imei}/channels":{"get":{"summary":"Get Available Dashcam & Mobile DVR Camera Channels","description":"Retrieves logical and physical camera video channels for a mobile digital video recorder (MDVR/dashcam) complying with JT/T 1078 (e.g. Channel 1 = Road View / Forward ADAS, Channel 2 = Driver Cabin / DMS, Channel 3 = Cargo Bay, Channel 4 = Rear View).","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit dashcam IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of camera channels with stream formats.","content":{"application/json":{"example":{"success":true,"data":[{"channel":1,"name":"Forward Road (ADAS)","stream_type":0,"ptz_supported":false},{"channel":2,"name":"Driver In-Cabin (DMS)","stream_type":0,"ptz_supported":false}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"],"security":[{"bearerAuth":[]}]}},"/api/video/{imei}/properties":{"post":{"summary":"Query terminal A/V capabilities","description":"Sends a 0x9003 command to the terminal to query its A/V capabilities (response 0x1003).","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/capabilities":{"get":{"summary":"Fetch full device capabilities","description":"Retrieves device capabilities from the database.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]},"post":{"summary":"Override terminal A/V capabilities manually","description":"Updates terminal audio/video capabilities manually in the database.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/stream/check":{"post":{"summary":"Ping camera with a tiny real stream","description":"Performs a pre-flight check to verify if the camera can successfully establish a stream.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/stream/start":{"post":{"summary":"Start JT/T 1078 Live Real-Time Video Stream","description":"Sends a JT/T 1078 0x9101 instruction to the dashcam terminal to establish an active RTP/AV stream to the media gateway, returning WebSocket or HLS live video URL for playback in the dashboard.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit dashcam IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Live stream session established with player URL.","content":{"application/json":{"example":{"success":true,"data":{"sessionId":"stream-864540081293581-ch1","wsUrl":"wss://video.vegagps.com/live/864540081293581_1.flv","hlsUrl":"https://video.vegagps.com/live/864540081293581_1/index.m3u8","channel":1}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channel"],"properties":{"channel":{"type":"integer","description":"Logical camera channel number (1-8)","example":1},"dataType":{"type":"integer","description":"0 = Audio & Video, 1 = Video only, 2 = Audio only","default":0,"example":0},"streamType":{"type":"integer","description":"0 = Sub-stream (low bandwidth), 1 = Main-stream (HD)","default":0,"example":0}}},"example":{"channel":1,"dataType":0,"streamType":0}}}}}},"/api/video/{imei}/stream/stop":{"post":{"summary":"Stop Active Live Video Stream","description":"Sends a 0x9102 instruction to tear down the live RTP media session and conserve cellular data on the dashcam SIM.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit dashcam IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Stream session closed."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channel"],"properties":{"channel":{"type":"integer","example":1}}},"example":{"channel":1}}}}}},"/api/video/{imei}/stream/proxy":{"get":{"summary":"Proxy stream through ffmpeg","description":"Proxies the live stream (e.g., transcoding HEVC to H.264).","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/stream/control":{"post":{"summary":"Control active stream","description":"Send control commands (e.g., change quality, switch sub/main stream) to an active live stream.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/audio/monitor/start":{"post":{"summary":"Start audio-only stream","description":"Starts listening to the cabin audio monitor stream.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/audio/monitor/stop":{"post":{"summary":"Stop audio monitor stream","description":"Stops the cabin audio monitor stream.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/ptt/start":{"post":{"summary":"Begin PTT session","description":"Initiates a Push-to-Talk (PTT) session to speak to the driver. Returns a WebRTC push URL.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/ptt/stop":{"post":{"summary":"End PTT session","description":"Ends an active Push-to-Talk (PTT) session.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/recordings/query":{"post":{"summary":"Search Remote SD Card Video Recordings","description":"Sends a 0x9205 command to search local SD card video clips stored on the dashcam device within a specified time range.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit dashcam IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of video files stored on terminal SD card."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channel","startTime","endTime"],"properties":{"channel":{"type":"integer","example":1},"startTime":{"type":"string","example":"2026-10-01 08:00:00"},"endTime":{"type":"string","example":"2026-10-01 10:00:00"},"alarmType":{"type":"integer","description":"0 for all, or specific JT/T alarm bitmask","default":0,"example":0}}},"example":{"channel":1,"startTime":"2026-10-01 08:00:00","endTime":"2026-10-01 10:00:00"}}}}}},"/api/video/{imei}/recordings":{"get":{"summary":"Fetch recording lists","description":"Retrieves previously queried recording lists from the database.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/recordings/download":{"get":{"summary":"Download historical recording segment","description":"Triggers playback and downloads the specified historical segment as an MP4 file.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/recordings/play":{"post":{"summary":"Start playback","description":"Commands the device to stream a specific historical recording.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/recordings/control":{"post":{"summary":"Control playback","description":"Send playback control commands (pause, seek, speed up/down) for historical recordings.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/ptz":{"post":{"summary":"Pan/Tilt/Zoom Control","description":"Send PTZ commands (Pan/Tilt/Zoom/Focus/Iris/Wiper/Infrared) to a compatible camera.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/config":{"post":{"summary":"Set video/safety parameters","description":"Configure terminal video and safety parameters (0x0075-0x007C, 0xF364-0xF367).","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/snippets":{"post":{"summary":"Manually trigger video snippet capture","description":"Queues a manual on-demand video snippet capture job.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]},"get":{"summary":"List captured video snippets","description":"Retrieves a list of video snippets captured on alarm triggers for a device.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/snippets/quota":{"get":{"summary":"Get video snippet storage quota usage","description":"Retrieves the total storage usage of video snippets for a device versus its quota.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/snippets/{id}":{"get":{"summary":"Get video snippet details","description":"Retrieves the details and playback URL for a specific video snippet.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Snippet UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]},"delete":{"summary":"Delete a video snippet","description":"Deletes a video snippet file from storage and its metadata record from the database.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Snippet UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/snippets/{id}/file":{"get":{"summary":"Stream video snippet MP4 file","description":"Streams a video snippet MP4 file with CORS and byte-range request support for browser video playback.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Snippet UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/jimi/internal/jimi/upload":{"post":{"description":"Provisions, dispatches, or creates a new Jimi Internal Jimi Upload in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imei":{"example":"any"},"filename":{"example":"any"},"fileName":{"example":"any"},"timestamp":{"example":"any"},"sign":{"example":"any"},"callbackBody":{"example":"any"},"fileType":{"example":"any"}}}}}},"tags":["Uploads & Media"],"summary":"Create or Trigger Jimi Internal Jimi Upload"}},"/api/jimi/upload":{"post":{"description":"Provisions, dispatches, or creates a new Jimi Upload in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imei":{"example":"any"},"filename":{"example":"any"},"fileName":{"example":"any"},"timestamp":{"example":"any"},"sign":{"example":"any"},"callbackBody":{"example":"any"},"fileType":{"example":"any"}}}}}},"tags":["Uploads & Media"],"summary":"Create or Trigger Jimi Upload"}},"/api/jimi/jimi/{imei}/uploads":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Jimi Jimi Imei Uploads within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"Get Jimi Jimi Imei Uploads"}},"/api/jimi/jimi/uploads/{id}/download":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Jimi Jimi Uploads Id Download within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"Get Jimi Jimi Uploads Id Download"}},"/api/jimi/jimi/uploads/{id}":{"delete":{"description":"Permanently removes or unlinks the target Jimi Jimi Uploads Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"Delete Jimi Jimi Uploads Id"}},"/api/trip-notes":{"get":{"description":"Retrieves a paginated list of Trip-notes accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Notes"],"summary":"Get Trip-notes"},"post":{"description":"Provisions, dispatches, or creates a new Trip-notes in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_imei":{"example":"any"},"trip_start":{"example":"any"},"trip_end":{"example":"any"},"label":{"example":"any"},"category":{"example":"any"},"note":{"example":"any"}}}}}},"tags":["Trip Notes"],"summary":"Create or Trigger Trip-notes"}},"/api/trip-notes/{id}":{"put":{"description":"Updates and overwrites properties of the target Trip-notes Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"example":"any"},"category":{"example":"any"},"note":{"example":"any"}}}}}},"tags":["Trip Notes"],"summary":"Update Trip-notes Id"},"delete":{"description":"Permanently removes or unlinks the target Trip-notes Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Notes"],"summary":"Delete Trip-notes Id"}},"/api/trips/templates":{"get":{"description":"Retrieves predefined commercial trip route templates (e.g. Factory-to-Port, Depot-to-Store) including planned stops, geofences, baseline transit durations, and fuel budgets.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"trip_type","in":"query","schema":{"type":"string"}},{"name":"is_active","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of configured trip templates.","content":{"application/json":{"example":{"success":true,"data":[{"id":"tmpl-dhk-ctg","name":"Dhaka to Chittagong Port Cargo Corridor","trip_type":"FR-RT","origin":"Tejgaon Industrial Area","destination":"Chittagong Port Yard 4","planned_distance_km":245,"estimated_hours":6.5,"fuel_budget_liters":75}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"List Master Trip Route Templates","security":[{"bearerAuth":[]}]},"post":{"description":"Defines a new standardized commercial trip blueprint with planned origin, destination, intermediate checkpoints, and cargo specifications.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Trip template created."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Create Master Trip Template","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","origin","destination"],"properties":{"name":{"type":"string","example":"Dhaka to Sylhet Express"},"origin":{"type":"string","example":"Dhaka Central Hub"},"destination":{"type":"string","example":"Sylhet Regional Depot"},"planned_distance_km":{"type":"number","example":240},"fuel_budget_liters":{"type":"number","example":65}}},"example":{"name":"Dhaka to Sylhet Express","origin":"Dhaka Central Hub","destination":"Sylhet Regional Depot","planned_distance_km":240,"fuel_budget_liters":65}}}}}},"/api/trips/templates/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Trips Templates Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Get Trips Templates Id"},"delete":{"description":"Permanently removes or unlinks the target Trips Templates Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Delete Trips Templates Id"}},"/api/trips/active":{"get":{"description":"Retrieves all vehicles currently on an active route, including transit progress, live ETA, route deviation status, and current driver.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of active dispatches in progress."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Get All Currently Active Dispatched Fleet Trips","security":[{"bearerAuth":[]}]}},"/api/trips/instances/active":{"get":{"description":"Retrieves a paginated list of Trips Instances Active accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Get Trips Instances Active"}},"/api/trips/instances":{"get":{"description":"Retrieves a paginated list of Trips Instances accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"imei","in":"query","schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"trip_type","in":"query","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Get Trips Instances"}},"/api/trips/instances/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Trips Instances Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Get Trips Instances Id"}},"/api/trips/instances/{id}/report":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Trips Instances Id Report within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Get Trips Instances Id Report"}},"/api/trips/instances/{id}/fuel-curve":{"get":{"description":"Calculates fuel burn efficiency across trip legs, correlating gradient changes, speed, vehicle load, and refuel events against distance travelled.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"trip-2026-10-001"},"description":"Trip instance ID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Correlated fuel vs distance points and consumption rate (KPL)."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Get Fuel Consumption vs Distance Telemetry Curve for Trip","security":[{"bearerAuth":[]}]}},"/api/trips/dispatch":{"post":{"description":"Initiates an active commercial dispatch for a vehicle, assigning driver, cargo manifest, trailer, and origin/destination checkpoints. Starts real-time compliance tracking.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Trip dispatched successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Dispatch New Vehicle Trip Instance","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_imei","origin","destination"],"properties":{"device_imei":{"type":"string","example":"864540081293581"},"template_id":{"type":"string","example":"tmpl-dhk-ctg"},"driver_id":{"type":"string","example":"drv-01"},"origin":{"type":"string","example":"Tejgaon Logistics Center"},"destination":{"type":"string","example":"Chittagong Port"},"cargo_weight_kg":{"type":"number","example":12500},"revenue_amount":{"type":"number","example":35000}}},"example":{"device_imei":"864540081293581","driver_id":"drv-01","origin":"Tejgaon Logistics Center","destination":"Chittagong Port","cargo_weight_kg":12500}}}}}},"/api/trips/instances/{id}/status":{"patch":{"description":"Applies partial field modifications to the target Trips Instances Id Status.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Modify Trips Instances Id Status"}},"/api/trips/instances/{id}/financials":{"patch":{"description":"Applies partial field modifications to the target Trips Instances Id Financials.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cargo_description":{"example":"any"},"cargo_weight_kg":{"example":"any"},"cargo_type":{"example":"any"},"revenue_amount":{"example":"any"},"revenue_currency":{"example":"any"},"fuel_expense_cost":{"example":"any"},"toll_expenses":{"example":"any"},"driver_allowance":{"example":"any"},"border_clearance_fees":{"example":"any"},"other_expenses":{"example":"any"}}}}}},"tags":["Trip Engine"],"summary":"Modify Trips Instances Id Financials"}},"/api/search":{"get":{"description":"Performs lightning-fast substring search across vehicle plates, names, device IMEIs, assigned drivers, and geofence locations in one query.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"q","in":"query","schema":{"type":"string","example":"Allion"},"required":true,"description":"Search keyword (plate, IMEI, driver name, vehicle model)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"Categorized search results.","content":{"application/json":{"example":{"success":true,"data":{"devices":[{"imei":"864540081293581","name":"Toyota Allion 2024","plate_number":"DHK-11-2041"}],"drivers":[],"geofences":[]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Search"],"summary":"Unified Global Search Across Entire Fleet","security":[{"bearerAuth":[]}]}},"/api/elocks":{"get":{"description":"Retrieves a paginated list of Elocks accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks"},"post":{"description":"Provisions, dispatches, or creates a new Elocks in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Create or Trigger Elocks"}},"/api/elocks/stats":{"get":{"description":"Retrieves a paginated list of Elocks Stats accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Stats"}},"/api/elocks/settings":{"get":{"description":"Retrieves a paginated list of Elocks Settings accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Settings"},"put":{"description":"Updates and overwrites properties of the target Elocks Settings.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Update Elocks Settings"}},"/api/elocks/tamper-events":{"get":{"description":"Retrieves a paginated list of Elocks Tamper-events accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"event_type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Tamper-events"}},"/api/elocks/alerts":{"get":{"description":"Retrieves a paginated list of Elocks Alerts accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"event_type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Alerts"}},"/api/elocks/inspections":{"get":{"description":"Retrieves a paginated list of Elocks Inspections accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Inspections"}},"/api/elocks/corridors":{"get":{"description":"Retrieves a paginated list of Elocks Corridors accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Corridors"}},"/api/elocks/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Elocks Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Id"},"put":{"description":"Updates and overwrites properties of the target Elocks Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Update Elocks Id"},"patch":{"description":"Applies partial field modifications to the target Elocks Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Modify Elocks Id"},"delete":{"description":"Permanently removes or unlinks the target Elocks Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Delete Elocks Id"}},"/api/elocks/{id}/readiness":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Elocks Id Readiness within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Id Readiness"}},"/api/elocks/{id}/dispatch":{"post":{"description":"Provisions, dispatches, or creates a new Elocks Id Dispatch in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Create or Trigger Elocks Id Dispatch"}},"/api/elocks/{id}/inspection":{"post":{"description":"Provisions, dispatches, or creates a new Elocks Id Inspection in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Create or Trigger Elocks Id Inspection"}},"/api/elocks/{id}/tamper-events":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Elocks Id Tamper-events within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"event_type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Id Tamper-events"}},"/api/elocks/{id}/inspections":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Elocks Id Inspections within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Id Inspections"}},"/api/coldchain/profiles":{"get":{"description":"Retrieves a paginated list of Coldchain Profiles accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"is_active","in":"query","schema":{"type":"string"}},{"name":"cargo_type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Coldchain Profiles"},"post":{"description":"Provisions, dispatches, or creates a new Coldchain Profiles in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Create or Trigger Coldchain Profiles"}},"/api/coldchain/profiles/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Coldchain Profiles Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Coldchain Profiles Id"},"put":{"description":"Updates and overwrites properties of the target Coldchain Profiles Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Update Coldchain Profiles Id"},"delete":{"description":"Permanently removes or unlinks the target Coldchain Profiles Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Delete Coldchain Profiles Id"}},"/api/coldchain/rate-cards":{"get":{"description":"Retrieves a paginated list of Coldchain Rate-cards accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"make","in":"query","schema":{"type":"string"}},{"name":"is_active","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Coldchain Rate-cards"},"post":{"description":"Provisions, dispatches, or creates a new Coldchain Rate-cards in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Create or Trigger Coldchain Rate-cards"}},"/api/coldchain/rate-cards/{id}":{"put":{"description":"Updates and overwrites properties of the target Coldchain Rate-cards Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Update Coldchain Rate-cards Id"},"delete":{"description":"Permanently removes or unlinks the target Coldchain Rate-cards Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Delete Coldchain Rate-cards Id"}},"/api/coldchain/pairings":{"get":{"description":"Retrieves a paginated list of Coldchain Pairings accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"is_active","in":"query","schema":{"type":"string"}},{"name":"origin_geofence_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Coldchain Pairings"},"post":{"description":"Provisions, dispatches, or creates a new Coldchain Pairings in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Create or Trigger Coldchain Pairings"}},"/api/coldchain/pairings/{id}":{"put":{"description":"Updates and overwrites properties of the target Coldchain Pairings Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Update Coldchain Pairings Id"},"delete":{"description":"Permanently removes or unlinks the target Coldchain Pairings Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Delete Coldchain Pairings Id"}},"/api/coldchain/scoring-weights":{"get":{"description":"Retrieves a paginated list of Coldchain Scoring-weights accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Coldchain Scoring-weights"},"put":{"description":"Updates and overwrites properties of the target Coldchain Scoring-weights.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Update Coldchain Scoring-weights"}},"/auth/register":{"post":{"description":"Provisions a new tenant organization and its initial administrator account.\n\n### Use Case\nSelf-service onboarding flow for new fleet customers. Automatically generates a unique tenant slug, initializes organization billing quotas, sets up default roles, and signs the user in.","responses":{"201":{"description":"Registration successful. Organization and user provisioned.","content":{"application/json":{"example":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","user":{"id":"d8e411fa-51a2-47d0-8f92-9118e47851ad","name":"Kariuki Kamau","email":"admin@safari-express.co.ke","role":"admin","org_id":"1e5e01b1-2182-4f05-b072-a7d0e1948831","org_name":"Safari Express Freight Ltd"}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"409":{"description":"Conflict: user with this email address already exists.","content":{"application/json":{"example":{"error":"User already exists"}}}},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"parameters":[],"summary":"Register New Organization & Admin Account","requestBody":{"required":true,"description":"New account and organization registration details","content":{"application/json":{"schema":{"type":"object","required":["name","email","password","orgName"],"properties":{"name":{"type":"string","description":"Full name of the primary administrator","example":"Kariuki Kamau"},"email":{"type":"string","format":"email","description":"Corporate email address for login and notifications","example":"admin@safari-express.co.ke"},"password":{"type":"string","format":"password","minLength":4,"maxLength":10,"description":"Account password (4 to 10 characters)","example":"Pass1234"},"orgName":{"type":"string","description":"Company or fleet organization legal name","example":"Safari Express Freight Ltd"}}},"example":{"name":"Kariuki Kamau","email":"admin@safari-express.co.ke","password":"Pass1234","orgName":"Safari Express Freight Ltd"}}}}}},"/auth/login":{"post":{"description":"Authenticates a user using their email, username, or phone number along with their password.\n\n### Use Case\nThis is the primary authentication entrypoint for web dashboards, mobile apps, and third-party API clients interacting with the Platform REST API (`/api/*`). Upon successful verification, the service issues a cryptographically signed JWT bearer token that must be supplied in subsequent requests.\n\n### Multi-Identifier Login\nThe `email` field accepts any of the following:\n- Registered email address (e.g. `ops@company.com`)\n- Phone number (e.g. `+8801712345678`)\n- Username (e.g. `dispatcher1`)","responses":{"200":{"description":"Login successful. Returns JWT access token and user profile context.","content":{"application/json":{"example":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJjMWY3Yjc2ZS0zNDdmLTQ0ZGUtOWU1Yy0wYzE1M2I2NjRkNGIiLCJvcmdJZCI6IjkwZTU0NGNlLWQyODQtNDhmMC1iOGQ0LTYzZmNiMDAxYTFjNSIsImlhdCI6MTc5MDg1MDIwMCwiZXhwIjoxNzkzNDQyMjAwfQ.Signature","user":{"id":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","name":"Fleet Dispatcher","email":"dispatcher@xeekar.com","role":"dispatcher","org_id":"90e544ce-d284-48f0-b8d4-63fcb001a1c5","org_name":"Xeekar Logistics","timezone":"Asia/Dhaka","is_platform_admin":false}}}}},"400":{"description":"Validation error: missing required fields or invalid format.","content":{"application/json":{"example":{"error":[{"code":"invalid_type","expected":"string","received":"undefined","path":["email"],"message":"Required"},{"code":"invalid_type","expected":"string","received":"undefined","path":["password"],"message":"Required"}]}}}},"401":{"description":"Authentication failure: invalid email/password combination.","content":{"application/json":{"example":{"error":"Invalid credentials"}}}},"403":{"description":"Account or Organization deactivated.","content":{"application/json":{"example":{"success":false,"error":"Your account has been temporarily deactivated. Please contact your administrator.","code":"ACCOUNT_DEACTIVATED"}}}},"429":{"description":"Rate limit exceeded: too many failed attempts (50 attempts per 10 minutes).","content":{"application/json":{"example":{"error":"Too many login attempts, please try again later."}}}},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"parameters":[],"summary":"Authenticate User & Obtain JWT Access Token","requestBody":{"required":true,"description":"User login credentials and session options","content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","description":"Registered user email, username, or phone number","example":"dispatcher@xeekar.com"},"password":{"type":"string","format":"password","description":"Account password","example":"SuperSecretPass123!"},"rememberMe":{"type":"boolean","description":"Extend token validity duration from standard (30 days) to persistent (90 days)","default":false,"example":true}}},"example":{"email":"dispatcher@xeekar.com","password":"SuperSecretPass123!","rememberMe":true}}}}}},"/auth/request-access":{"post":{"description":"Provisions, dispatches, or creates a new Auth Request-access in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"parameters":[],"summary":"Create or Trigger Auth Request-access"}},"/auth/signup-requests":{"get":{"description":"Retrieves a paginated list of Auth Signup-requests accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"summary":"Get Auth Signup-requests"}},"/auth/signup-requests/{id}/approve":{"patch":{"description":"Applies partial field modifications to the target Auth Signup-requests Id Approve.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"summary":"Modify Auth Signup-requests Id Approve"}},"/auth/signup-requests/{id}/reject":{"patch":{"description":"Applies partial field modifications to the target Auth Signup-requests Id Reject.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"example":"any"}}}}}},"tags":["Authentication"],"summary":"Modify Auth Signup-requests Id Reject"}},"/auth/forgot-password":{"post":{"description":"Sends a cryptographically secure, time-limited password reset link to the user's verified email address.\n\n### Use Case\nUser self-service recovery when credentials are lost. Rate-limited to prevent abuse.","responses":{"200":{"description":"Reset request received. An email is dispatched if the user exists.","content":{"application/json":{"example":{"success":true,"message":"Password reset link sent to your email."}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"parameters":[],"summary":"Request Password Reset Email Link","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Registered user email address","example":"user@company.com"}}},"example":{"email":"user@company.com"}}}}}},"/auth/reset-password":{"post":{"description":"Completes the password reset process using the secure token received via email.","responses":{"200":{"description":"Password successfully updated. All previous sessions invalidated.","content":{"application/json":{"example":{"success":true,"message":"Password has been reset successfully."}}}},"400":{"description":"Invalid or expired reset token."},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"parameters":[],"summary":"Reset Password Using Token","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","newPassword"],"properties":{"token":{"type":"string","description":"Reset token from the email link query string","example":"9fa82b5d4e1c..."},"newPassword":{"type":"string","format":"password","description":"New secure password (min 8 characters)","example":"NewSecurePass2026!"}}},"example":{"token":"9fa82b5d4e1c...","newPassword":"NewSecurePass2026!"}}}}}},"/auth/logout":{"post":{"description":"Invalidates the current session token in Redis and server session registry.\n\n### Use Case\nEnsures secure sign-out. After calling this endpoint, the token cannot be used again even if it has not yet expired.","parameters":[],"responses":{"200":{"description":"Logged out successfully.","content":{"application/json":{"example":{"success":true,"message":"Logged out successfully"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"summary":"Terminate Active Session & Revoke Token","security":[{"bearerAuth":[]}]}},"/auth/change-password":{"put":{"description":"Allows an authenticated user to change their account password by verifying their current password.","parameters":[],"responses":{"200":{"description":"Password changed successfully."},"400":{"description":"Bad Request"},"401":{"description":"Incorrect current password."},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"summary":"Change Password for Authenticated User","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["currentPassword","newPassword"],"properties":{"currentPassword":{"type":"string","format":"password","description":"Current valid password","example":"CurrentPass123!"},"newPassword":{"type":"string","format":"password","description":"New secure password (min 8 characters)","example":"UpdatedSecurePass456!"}}},"example":{"currentPassword":"CurrentPass123!","newPassword":"UpdatedSecurePass456!"}}}}}},"/auth/me":{"get":{"description":"Retrieves the full profile, active session context, organization details, and permissions of the currently authenticated token.\n\n### Use Case\nUsed during application bootstrap and page refreshes to verify token validity, fetch permissions for UI feature flags, and hydrate active organization state.","parameters":[],"responses":{"200":{"description":"Current user profile context.","content":{"application/json":{"example":{"user":{"id":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","name":"Fleet Dispatcher","email":"dispatcher@xeekar.com","role":"dispatcher","org_id":"90e544ce-d284-48f0-b8d4-63fcb001a1c5","org_name":"Xeekar Logistics","timezone":"Asia/Dhaka","is_platform_admin":false,"permissions":["devices:view","devices:edit","tracking:live","reports:generate","commands:send"]}}}}},"401":{"description":"Unauthorized: missing, expired, or corrupted Bearer JWT token."},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Authentication"],"summary":"Get Current Authenticated User Profile & Permissions","security":[{"bearerAuth":[]}]}},"/auth/sessions":{"get":{"description":"Returns active sessions associated with the current user, including client IP, device model, user-agent, and login timestamp.","parameters":[],"responses":{"200":{"description":"List of active sessions.","content":{"application/json":{"example":{"sessions":[{"id":"sess_91b72e","ip":"103.205.134.12","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)","device_name":"Chrome on macOS","current":true,"created_at":"2026-10-01T08:30:00Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"summary":"List All Active User Sessions","security":[{"bearerAuth":[]}]}},"/auth/sessions/{sessionId}":{"delete":{"description":"Terminates a specific remote session by session ID.","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","example":"sess_91b72e"},"description":"Session identifier to terminate"}],"responses":{"200":{"description":"Session successfully revoked."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"summary":"Revoke Specific User Session","security":[{"bearerAuth":[]}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"JWT Bearer token. Format: `Bearer `"},"apiKeyAuth":{"type":"apiKey","in":"query","name":"api_key","description":"Organization API Key for V1 Public Integration endpoints"}}},"security":[{"bearerAuth":[]}],"default":{"openapi":"3.0.0","info":{"title":"Vega Telematics Developer API","version":"4.5.0","description":"# Vega Telematics & Fleet Developer Platform\n\nWelcome to the **Vega Telematics Developer Platform**. Vega provides mission-critical enterprise IoT GPS tracking, fleet management, video telematics, fuel intelligence, remote immobilizer commands, and real-time streaming infrastructure.\n\n---\n\n## 🚀 Quickstart & Architecture Overview\n\nThe Vega Platform offers two complementary API layers depending on your integration architecture:\n\n| API Layer | Base Path | Authentication | Intended Use Case |\n| :--- | :--- | :--- | :--- |\n| **Public Integration API** | `/v1/...` | `api_key` + `organization_name` + `email` query params | ERP, TMS, BRTA/Government compliance, dispatch, billing, and accounting systems. Fast zero-session server-to-server calls. |\n| **Platform REST API** | `/api/...` | `Authorization: Bearer ` header | Full fleet operations, live device tracking, geofence CRUD, alerts, sensor telemetry, video streaming, reports, and administrative management. |\n\n---\n\n## 🌐 Environments & Base URLs\n\nAlways use our production gateway for high availability, automatic load balancing, and unbuffered SSE streaming:\n\n- **Primary API Gateway**: `https://api.vegagps.com` (Recommended for all external integrations)\n- **Direct Platform Host**: `https://track.vegagps.com`\n- **Interactive Developer Portal**: `https://docs.vegagps.com`\n\n---\n\n## 🔐 Authentication Guide\n\n### Method A: Public Integration API Key (for `/v1/*`)\n\nFor external third-party software (e.g. BRTA, Transport Management Systems, SAP/Odoo ERPs), pass your credentials as standard query parameters with every request:\n\n```http\nGET /v1/vehicles/current-location?organization_name=Xeekar&email=dispatcher@xeekar.com&api_key=vg_live_xxxxxxxx&vehicle_id=864540081293581 HTTP/1.1\nHost: api.vegagps.com\n```\n\n- **`api_key`**: Your organization's API Secret Key (obtained from your Platform Admin under *Organization Settings* > *API Keys*).\n- **`organization_name`**: Your company or organization identifier (e.g., `Xeekar`).\n- **`email`**: An active user's email within your organization for audit trail and scope enforcement.\n- **`vehicle_id`**: Target vehicle registration plate, internal vehicle UUID, or device IMEI.\n\n---\n\n### Method B: JWT Bearer Token (for `/api/*`)\n\nFor direct integration with the full platform features:\n\n#### 1. Obtain an Access Token\nSend a POST request to `/auth/login`:\n\n```bash\ncurl -X POST https://api.vegagps.com/auth/login \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"email\": \"user@company.com\",\n \"password\": \"your_secure_password\"\n }'\n```\n\n**Response:**\n```json\n{\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"user\": {\n \"id\": \"c1f7b76e-347f-44de-9e5c-0c153b664d4b\",\n \"name\": \"Operations Team\",\n \"email\": \"user@company.com\",\n \"role\": \"admin\",\n \"org_id\": \"90e544ce-d284-48f0-b8d4-63fcb001a1c5\"\n }\n}\n```\n\n#### 2. Authorize Requests\nPass the returned token in the `Authorization` header of subsequent calls:\n\n```bash\ncurl https://api.vegagps.com/api/devices \\\n -H \"Authorization: Bearer \"\n```\n\n---\n\n## 💡 Practical Integration Recipes\n\n### Recipe 1: Fetch Live Location of a Vehicle (Integration API)\n\n```bash\ncurl \"https://api.vegagps.com/v1/vehicles/current-location?organization_name=Xeekar&email=ops@xeekar.com&api_key=YOUR_API_KEY&vehicle_id=864540081293581\"\n```\n\n```javascript\n// Node.js (Fetch)\nconst params = new URLSearchParams({\n organization_name: 'Xeekar',\n email: 'ops@xeekar.com',\n api_key: 'YOUR_API_KEY',\n vehicle_id: '864540081293581'\n});\n\nconst response = await fetch(`https://api.vegagps.com/v1/vehicles/current-location?${params}`);\nconst data = await response.json();\nconsole.log('Vehicle speed:', data.speed, 'Coordinates:', data.latitude, data.longitude);\n```\n\n```python\n# Python (Requests)\nimport requests\n\nparams = {\n 'organization_name': 'Xeekar',\n 'email': 'ops@xeekar.com',\n 'api_key': 'YOUR_API_KEY',\n 'vehicle_id': '864540081293581'\n}\n\nres = requests.get('https://api.vegagps.com/v1/vehicles/current-location', params=params)\ntelemetry = res.json()\nprint(f\"Lat: {telemetry['latitude']}, Lon: {telemetry['longitude']}, Ignition: {telemetry['ignition']}\")\n```\n\n---\n\n### Recipe 2: Bulk Fleet Status (All Active Vehicles)\n\n```bash\ncurl \"https://api.vegagps.com/v1/vehicles/current-locations?organization_name=Xeekar&email=ops@xeekar.com&api_key=YOUR_API_KEY\"\n```\n\nReturns an array of current locations, speed, ignition status, address, and device connectivity timestamps for every vehicle in your fleet in a single call.\n\n---\n\n### Recipe 3: Real-Time Telemetry Streaming via Server-Sent Events (SSE)\n\nConnect to the live positions event stream without continuous polling:\n\n```javascript\nconst eventSource = new EventSource('https://api.vegagps.com/api/stream/events?token=' + JWT_TOKEN);\n\neventSource.onmessage = (event) => {\n const position = JSON.parse(event.data);\n console.log('Live location update:', position.device_id, position.latitude, position.longitude);\n};\n\neventSource.onerror = (err) => {\n console.error('SSE connection error, will reconnect automatically:', err);\n};\n```\n\n---\n\n### Recipe 4: Remote Engine Cutoff / Mobilizer Command\n\n```bash\ncurl -X POST https://api.${BASE_DOMAIN}/api/commands/send \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"deviceId\": \"c1f7b76e-347f-44de-9e5c-0c153b664d4b\",\n \"commandType\": \"RELAY_STOP\"\n }'\n```\n\n---\n\n### Recipe 5: ERP & Fleet Provisioning Integration (Users, Devices, Assignments & Coin Billing)\n\nFor partners automating client accounts and vehicle onboarding from an internal ERP, CRM, or billing system (e.g. GPSWOX migrations):\n\n#### 1. Device Expiration vs Prepaid Coins Architecture\n- **Single Source of Truth Expiration (`subscription_end`)**: Every vehicle has a single expiration date. When this date passes, the vehicle automatically transitions to expired status.\n- **Prepaid Coins**: Coins represent your organization's prepaid tracking credits with Vega:\n - **Adding a device** automatically debits **1 Coin** and provisions **12 months (365 days)** of validity.\n - **Renewing a device** debits **1 Coin** and extends validity by another **12 months**.\n - **Client User Accounts**: Do not expire per-device; manage client access by activating or suspending user accounts.\n\n#### 2. Workflow: Onboard Customer, Register Device & Link Access\n\n##### Step A: Create Client User\n```bash\ncurl -X POST https://api.${BASE_DOMAIN}/api/users \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Acme Logistics\",\n \"email\": \"ops@acmelogistics.com\",\n \"phone\": \"+8801700000000\",\n \"password\": \"TempPassword123\",\n \"role_id\": \"1059166a-54ee-4ced-aa7e-c36053f59a24\"\n }'\n```\n*(Returns user UUID: `{\"success\": true, \"data\": {\"id\": \"c1f7b76e-...\"}}`)*\n\n##### Step B: Provision Hardware Device (Auto-debits 1 coin, sets 1-year validity)\n```bash\ncurl -X POST https://api.${BASE_DOMAIN}/api/devices \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"imei\": \"864540081293581\",\n \"name\": \"Toyota Premio - DHK-METRO-GA-11-2041\",\n \"plate_number\": \"DHK-METRO-GA-11-2041\",\n \"sim_number\": \"+8801812345678\",\n \"model\": \"Concox GT06\",\n \"user_ids\": [\"c1f7b76e-347f-44de-9e5c-0c153b664d4b\"]\n }'\n```\n\n##### Step C: Renew Device Subscription (Extends by 12 months)\n```bash\ncurl -X POST https://api.${BASE_DOMAIN}/api/devices/864540081293581/renew \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"coins\": 1\n }'\n```\n\n##### Step D: Assign or Replace Users on Device\n```bash\ncurl -X PUT https://api.${BASE_DOMAIN}/api/devices/864540081293581/assigned-users \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"user_ids\": [\"c1f7b76e-347f-44de-9e5c-0c153b664d4b\"]\n }'\n```\n\n##### Step E: Suspend or Reactivate Client Account (ERP Billing Hook)\n```bash\ncurl -X PATCH https://api.${BASE_DOMAIN}/api/users/c1f7b76e-347f-44de-9e5c-0c153b664d4b/status \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"active\": false\n }'\n```\n\n##### Step F: Check Organization Coin Balance\n```bash\ncurl https://api.${BASE_DOMAIN}/api/billing/balance \\\n -H \"Authorization: Bearer \"\n```\n\n---\n\n## 📊 Standard HTTP Response Codes\n\n| Status Code | Description | Typical Cause / Resolution |\n| :--- | :--- | :--- |\n| **`200 OK`** | Request succeeded | Target data returned in response body. |\n| **`201 Created`** | Resource created | Device, geofence, or user was successfully provisioned. |\n| **`400 Bad Request`** | Validation error | Missing required parameters (`api_key`, `organization_name`, etc.) or invalid JSON payload. |\n| **`401 Unauthorized`** | Authentication failed | Missing, expired, or invalid API key or JWT token. |\n| **`403 Forbidden`** | Access denied | User or key does not have permission to access the requested organization or vehicle. |\n| **`404 Not Found`** | Resource not found | Vehicle, device ID, or endpoint URL does not exist. |\n| **`429 Too Many Requests`** | Rate limit exceeded | Back off and retry. Default limit is 1,000 requests per 15 minutes. |\n| **`500 Internal Error`** | Server error | An unexpected server error occurred. Contact support with the `x-request-id` header. |\n","contact":{"name":"Vega Telematics Developer Support","url":"https://vegagps.com"}},"servers":[{"url":"https://api.vegagps.com","description":"Production API Gateway (Recommended)"},{"url":"https://track.vegagps.com","description":"Tracking Platform Direct"},{"url":"https://docs.vegagps.com","description":"Documentation Proxy"}],"tags":[{"name":"Public Integration API","description":"V1 public integration endpoints (API Key authentication) for ERP, TMS, and Government systems"},{"name":"Authentication","description":"User authentication, registration, access requests, password resets, and session management"},{"name":"Health","description":"Service health checks and cron heartbeats"},{"name":"Devices","description":"Device CRUD, fleet assignment, subscriptions"},{"name":"Positions","description":"GPS position history queries"},{"name":"Streams","description":"Server-Sent Events (SSE) for live tracking positions, alerts, and system status"},{"name":"Fleets","description":"Fleet/group management"},{"name":"Drivers","description":"Driver management and vehicle assignment"},{"name":"Trailers","description":"Trailers and asset hitching/unhitching management"},{"name":"Favorites","description":"Favorite/pinned device management"},{"name":"Alerts","description":"Alert rules, history, and templates"},{"name":"Geofences","description":"Geofence CRUD (circle/polygon)"},{"name":"Notification Profiles","description":"Notification group profiles"},{"name":"Notification Templates","description":"Notification email, SMS, push, and webhook templates"},{"name":"Notifications","description":"In-app notifications and alert inbox"},{"name":"Reports","description":"Report generation, storage, and scheduling"},{"name":"Analytics","description":"Dashboard analytics and KPIs"},{"name":"Trip Engine","description":"Enterprise commercial trip dispatch, leg scoring, fuel curves, and cargo accounting"},{"name":"Bulk Fuel Tanks","description":"Yard stationary fuel storage tanks, intake logs, and vehicle dispensations"},{"name":"Stats","description":"Fleet statistics"},{"name":"Video Telematics","description":"JT/T 1078 live video streaming, playback, PTZ control, and health monitoring"},{"name":"Uploads & Media","description":"Jimi IoT dashcam media uploads, video recordings, and alarm attachments"},{"name":"Sensors","description":"Sensor templates and device sensor configuration"},{"name":"Commands","description":"GPRS command interface (engine cutoff, etc.)"},{"name":"Maintenance","description":"Service intervals and maintenance logs"},{"name":"Inspections","description":"Vehicle inspection checklists and defect reporting"},{"name":"Expenses","description":"Fleet expense tracking, fuel logs, and cost summaries"},{"name":"Tasks","description":"Task/job dispatch"},{"name":"Routes","description":"Route planning and management"},{"name":"POI","description":"Points of Interest library"},{"name":"Trip Notes","description":"Trip annotations and operational notes"},{"name":"Bulk Operations","description":"Bulk device operations (import, delete, assign)"},{"name":"Share","description":"Public tracking link sharing"},{"name":"Chat","description":"Driver-dispatcher and platform in-app messaging"},{"name":"AI Assistant","description":"AI-powered natural language fleet queries and intelligent insights"},{"name":"Search","description":"Unified global search across devices, drivers, fleets, and geofences"},{"name":"Fuel Prices","description":"Live fuel price discovery and nearest station locator"},{"name":"Weather","description":"Live weather conditions for device coordinates"},{"name":"Certificates","description":"GPS tracker installation and compliance certificates"},{"name":"Users","description":"User management (admin only)"},{"name":"Organizations","description":"Organization settings and billing"},{"name":"Roles","description":"Custom roles and permissions"},{"name":"Custom Fields","description":"Dynamic custom entity fields and schemas"},{"name":"Domains","description":"Custom domain management and SSL/TLS verification"},{"name":"Branding","description":"White-label branding configuration"},{"name":"Billing","description":"Coin-based billing and balance transactions"},{"name":"Payments","description":"Subscription plans and payment gateway integration"},{"name":"Security","description":"Security dashboard, session controls, and access logs"},{"name":"IP Management","description":"Rate limit and IP blacklist management"},{"name":"Admin Diagnostics","description":"Raw binary packet inspection and system performance metrics"},{"name":"Settings","description":"System settings (device timeout, speed thresholds)"},{"name":"Unknown Devices","description":"Device onboarding / pending approval"},{"name":"Simulator","description":"GPS device simulator control"},{"name":"Telemetry","description":"Mobile app crash logs and performance telemetry"}],"paths":{"/health":{"get":{"description":"Retrieves a paginated list of Health accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Health"],"parameters":[],"summary":"Get Health"}},"/health/crons":{"get":{"description":"Retrieves a paginated list of Health Crons accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Health"],"summary":"Get Health Crons"}},"/health/reconnects":{"get":{"description":"Retrieves a paginated list of Health Reconnects accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Health"],"summary":"Get Health Reconnects"}},"/internal/metrics":{"get":{"description":"Retrieves a paginated list of Internal Metrics accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Health"],"summary":"Get Internal Metrics"}},"/internal/device-exists/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Internal Device-exists Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"}],"responses":{"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Health"],"summary":"Get Internal Device-exists Imei"}},"/api/internal/verify-domain":{"get":{"description":"Retrieves a paginated list of Internal Verify-domain accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"domain","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Domains"],"summary":"Get Internal Verify-domain"}},"/upload":{"post":{"description":"Provisions, dispatches, or creates a new Upload in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imei":{"example":"any"},"filename":{"example":"any"},"fileName":{"example":"any"},"timestamp":{"example":"any"},"sign":{"example":"any"},"callbackBody":{"example":"any"},"fileType":{"example":"any"}}}}}},"tags":["Uploads & Media"],"summary":"Create or Trigger Upload"}},"/api/upload":{"post":{"description":"Provisions, dispatches, or creates a new Upload in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imei":{"example":"any"},"filename":{"example":"any"},"fileName":{"example":"any"},"timestamp":{"example":"any"},"sign":{"example":"any"},"callbackBody":{"example":"any"},"fileType":{"example":"any"}}}}}},"tags":["Uploads & Media"],"summary":"Create or Trigger Upload"}},"/api/internal/jimi/upload":{"post":{"description":"Provisions, dispatches, or creates a new Internal Jimi Upload in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imei":{"example":"any"},"filename":{"example":"any"},"fileName":{"example":"any"},"timestamp":{"example":"any"},"sign":{"example":"any"},"callbackBody":{"example":"any"},"fileType":{"example":"any"}}}}}},"tags":["Uploads & Media"],"summary":"Create or Trigger Internal Jimi Upload"}},"/api/admin/packets/devices":{"get":{"description":"Retrieves a paginated list of Admin Packets Devices accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Admin Diagnostics"],"summary":"Get Admin Packets Devices"}},"/api/admin/devices/{imei}/packets":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Admin Devices Imei Packets within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Admin Devices Imei Packets"}},"/api/internal/media/on_publish":{"post":{"description":"Provisions, dispatches, or creates a new Internal Media On_publish in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"stream":{"example":"any"},"type":{"example":"any"},"session":{"example":"any"}}}}}},"tags":["Video Telematics"],"summary":"Create or Trigger Internal Media On_publish"}},"/api/internal/media/on_publish_done":{"post":{"description":"Provisions, dispatches, or creates a new Internal Media On_publish_done in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"stream":{"example":"any"},"type":{"example":"any"},"session":{"example":"any"}}}}}},"tags":["Video Telematics"],"summary":"Create or Trigger Internal Media On_publish_done"}},"/api/internal/media/on_idle_timeout":{"post":{"description":"Provisions, dispatches, or creates a new Internal Media On_idle_timeout in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"stream":{"example":"any"},"type":{"example":"any"},"session":{"example":"any"}}}}}},"tags":["Video Telematics"],"summary":"Create or Trigger Internal Media On_idle_timeout"}},"/api/branding":{"get":{"description":"Retrieves white-label logo URL, favicon, page title, company support email, and primary accent theme color.","parameters":[{"name":"domain","in":"query","schema":{"type":"string"}},{"name":"slug","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Branding configuration."},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Branding"],"summary":"Get White-Label Custom Branding Assets & Theme","security":[{"bearerAuth":[]}]}},"/api/branding/mobile/{slug}":{"get":{"description":"Retrieves a paginated list of Branding Mobile Slug accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"tags":["Branding"],"summary":"Get Branding Mobile Slug"}},"/api/metadata":{"get":{"description":"Retrieves a paginated list of Metadata accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"domain","in":"query","schema":{"type":"string"}},{"name":"slug","in":"query","schema":{"type":"string"}},{"name":"path","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Branding"],"summary":"Get Metadata"}},"/api/metadata/manifest":{"get":{"description":"Retrieves a paginated list of Metadata Manifest accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","produces":["application/manifest+json"],"parameters":[{"name":"domain","in":"query","schema":{"type":"string"}},{"name":"slug","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Branding"],"summary":"Get Metadata Manifest"}},"/api/share/verify-certificate/{certNo}":{"get":{"description":"Retrieves a paginated list of Share Verify-certificate CertNo accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"certNo","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"tags":["Share"],"summary":"Get Share Verify-certificate CertNo"}},"/api/share/{token}":{"get":{"description":"Retrieves a paginated list of Share Token accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"tags":["Share"],"summary":"Get Share Token"}},"/api/share":{"get":{"description":"Retrieves a paginated list of Share accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Share"],"summary":"Get Share"},"post":{"description":"Provisions, dispatches, or creates a new Share in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resource_type":{"example":"any"},"resource_id":{"example":"any"},"duration_hours":{"example":"any"},"duration_days":{"example":"any"}}}}}},"tags":["Share"],"summary":"Create or Trigger Share"}},"/api/share/{id}":{"delete":{"description":"Permanently removes or unlinks the target Share Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Share"],"summary":"Delete Share Id"}},"/api/telemetry/mobile":{"post":{"description":"Provisions, dispatches, or creates a new Telemetry Mobile in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"events":{"example":"any"}}}}}},"tags":["Telemetry"],"summary":"Create or Trigger Telemetry Mobile"}},"/api/v1/telemetry/ingest/pilot":{"post":{"description":"Provisions, dispatches, or creates a new Telemetry Ingest Pilot in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"summary":"Create or Trigger Telemetry Ingest Pilot"}},"/v1/vehicles/current-location":{"get":{"description":"Retrieves real-time GPS coordinates, speed, heading, ignition state, and last reported timestamp for a single vehicle.\n\n### Use Case\nIdeal for single-vehicle tracking widgets, customer dispatch tracking portals, BRTA government compliance pushes, or ERP systems updating active vehicle coordinates.\n\n### Authentication\nRequires `organization_name`, `email`, and `api_key` passed as query parameters.\n\n### Vehicle Identifier\nYou can supply either the device **IMEI** (e.g. `864540081293581`), the vehicle **registration plate** (e.g. `DHK-METRO-GA-11-2041`), or internal **vehicle_id**.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"organization_name","in":"query","schema":{"type":"string","example":"Xeekar"},"required":true,"description":"Organization name or slug (e.g. Xeekar)"},{"name":"vehicle_id","in":"query","schema":{"type":"string","example":"864540081293581"},"required":true,"description":"Target vehicle identifier: device IMEI, license plate number, or vehicle UUID"},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email address for authorization and audit trail"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API secret key (from Organization Settings > API Keys)"}],"responses":{"200":{"description":"Real-time vehicle location and telemetry data.","content":{"application/json":{"example":{"success":true,"message":"Vehicle location fetched successfully.","data":[{"vehicle_id":"864540081293581","vehicle_name":"Toyota Allion 2024","registration_number":"DHK-METRO-GA-11-2041","vehicle_type":"Car","ignition_status":"ON","speed":48,"heading":184,"timestamp":"2026-10-01T10:15:30.000Z","location":{"latitude":23.810332,"longitude":90.412518}}]}}}},"400":{"description":"Missing required query parameters.","content":{"application/json":{"example":{"success":false,"message":"Missing required query parameters: organization_name (or organization_id), email, and api_key are required."}}}},"401":{"description":"Invalid or expired API key, unknown organization, or inactive user email."},"403":{"description":"Forbidden"},"404":{"description":"Vehicle not found within this organization."},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get Live Location & Telemetry for a Specific Vehicle"}},"/v1/vehicles/current-locations":{"get":{"description":"Retrieves current coordinates, speed, heading, and ignition status for every active vehicle in your fleet in a single high-performance API call.\n\n### Use Case\nIdeal for dispatch centers, central monitoring screens, GIS integrations, and third-party TMS synchronizing whole-fleet positions every 10–30 seconds.\n\n### Filtering Options\nYou can optionally filter by `status` (`moving`, `idle`, `stopped`, `offline`) or by `fleet_id`.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"organization_name","in":"query","schema":{"type":"string","example":"Xeekar"},"required":true,"description":"Organization name or slug (e.g. Xeekar)"},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email address"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API secret key"},{"name":"fleet_id","in":"query","schema":{"type":"string","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b"},"required":false,"description":"Filter vehicles by specific fleet group ID"},{"name":"status","in":"query","schema":{"type":"string","example":"moving","enum":["moving","idle","stopped","offline"]},"required":false,"description":"Filter by current vehicle operational motion status"}],"responses":{"200":{"description":"Bulk array of current vehicle locations and fleet count.","content":{"application/json":{"example":{"success":true,"message":"Vehicle locations fetched successfully.","vehicle_count":2,"data":[{"vehicle_id":"864540081293581","vehicle_name":"Toyota Allion 2024","registration_number":"DHK-METRO-GA-11-2041","vehicle_type":"Car","ignition_status":"ON","speed":55,"heading":192,"timestamp":"2026-10-01T10:15:30.000Z","location":{"latitude":23.810332,"longitude":90.412518}},{"vehicle_id":"865167047241865","vehicle_name":"Hino 500 Heavy Truck","registration_number":"RAJ-BA-11-0079","vehicle_type":"Truck","ignition_status":"OFF","speed":0,"heading":45,"timestamp":"2026-10-01T10:14:15.000Z","location":{"latitude":24.363588,"longitude":88.624135}}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get Bulk Live Locations for All Active Fleet Vehicles"}},"/v1/fleet/status":{"get":{"description":"Returns aggregate counts of fleet vehicles categorized by motion state: moving, idling, parked/stopped, and offline.\n\n### Use Case\nExecutive dashboards, KPI widgets, and high-level health monitors that need quick numerical status without downloading coordinates.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API key"},{"name":"organization_name","in":"query","required":true,"description":"Organization name or slug","schema":{"type":"string","example":"Xeekar"}}],"responses":{"200":{"description":"High-level fleet summary counts.","content":{"application/json":{"example":{"success":true,"data":{"total_vehicles":120,"moving":48,"idle":14,"stopped":52,"offline":6}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get High-Level Fleet Operational Status & Breakdown Counts"}},"/v1/vehicles/registry":{"get":{"description":"Returns the full catalog of enrolled vehicles in the organization, including vehicle model, registration plates, installed tracker hardware IMEI, and device model.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API key"},{"name":"organization_name","in":"query","required":true,"description":"Organization name or slug","schema":{"type":"string","example":"Xeekar"}}],"responses":{"200":{"description":"List of registered fleet vehicles.","content":{"application/json":{"example":{"success":true,"data":[{"vehicle_id":"864540081293581","registration_number":"DHK-METRO-GA-11-2041","vehicle_name":"Toyota Allion 2024","vehicle_type":"Car","device_model":"GT06Pro","speed_limit_kmh":80}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get Complete Vehicle Registry & Hardware Inventory"}},"/v1/vehicles/trip-history":{"get":{"description":"Returns historical timestamped GPS points, speed, and heading over a specified time window.\n\n### Use Case\nRoute playback recreation, driver route compliance audits, and route corridor verification.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API key"},{"name":"vehicle_id","in":"query","schema":{"type":"string","example":"864540081293581"},"required":true,"description":"Vehicle IMEI or license plate number"},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"organization_name","in":"query","required":true,"description":"Organization name or slug","schema":{"type":"string","example":"Xeekar"}},{"name":"from","in":"query","required":true,"description":"Start timestamp (ISO-8601 UTC)","schema":{"type":"string","example":"2026-10-01T00:00:00Z"}},{"name":"to","in":"query","required":true,"description":"End timestamp (ISO-8601 UTC)","schema":{"type":"string","example":"2026-10-01T23:59:59Z"}}],"responses":{"200":{"description":"Chronological GPS track waypoints.","content":{"application/json":{"example":{"success":true,"vehicle_id":"864540081293581","points_count":240,"data":[{"timestamp":"2026-10-01T08:00:10Z","latitude":23.8103,"longitude":90.4125,"speed":42,"heading":180,"ignition":true}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get Historical Waypoint Trajectory & Trip Track for a Vehicle"}},"/v1/vehicles/daily-distance":{"get":{"description":"Calculates total distance traveled in kilometers, engine operating hours, and idle duration grouped by vehicle and day.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API key"},{"name":"vehicle_id","in":"query","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"organization_name","in":"query","required":true,"description":"Organization name or slug","schema":{"type":"string","example":"Xeekar"}},{"name":"date","in":"query","required":false,"description":"Target date (YYYY-MM-DD). Defaults to today.","schema":{"type":"string","example":"2026-10-01"}}],"responses":{"200":{"description":"Daily mileage summary per vehicle.","content":{"application/json":{"example":{"success":true,"date":"2026-10-01","data":[{"vehicle_id":"864540081293581","registration_number":"DHK-METRO-GA-11-2041","distance_km":148.6,"engine_hours":4.8,"idle_hours":0.9,"max_speed":78}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get Daily Distance Driven & Mileage Report"}},"/v1/vehicles/stop-report":{"get":{"description":"Lists all vehicle stops, parking locations, stop durations, and arrival/departure timestamps.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API key"},{"name":"vehicle_id","in":"query","schema":{"type":"string","example":"864540081293581"},"required":true,"description":"Vehicle identifier"},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"organization_name","in":"query","required":true,"description":"Organization name or slug","schema":{"type":"string","example":"Xeekar"}}],"responses":{"200":{"description":"List of recorded vehicle stops.","content":{"application/json":{"example":{"success":true,"data":[{"stopped_at":"2026-10-01T09:12:00Z","departed_at":"2026-10-01T09:45:00Z","duration_minutes":33,"latitude":23.8211,"longitude":90.4285,"location_name":"Uttara Sector 7 Depot, Dhaka"}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get Vehicle Parking & Stop Report"}},"/v1/vehicles/overspeed-violations":{"get":{"description":"Returns overspeed violations where a vehicle exceeded its configured maximum speed threshold.","parameters":[{"name":"organization_id","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string","example":"developer@xeekar.com"},"required":true,"description":"Registered user email"},{"name":"api_key","in":"query","schema":{"type":"string","example":"vg_live_948f21..."},"required":true,"description":"Organization API key"},{"name":"vehicle_id","in":"query","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"organization_name","in":"query","required":true,"description":"Organization name or slug","schema":{"type":"string","example":"Xeekar"}}],"responses":{"200":{"description":"List of recorded overspeed incidents.","content":{"application/json":{"example":{"success":true,"data":[{"vehicle_id":"864540081293581","registration_number":"DHK-METRO-GA-11-2041","speed":92,"speed_limit":80,"timestamp":"2026-10-01T09:30:15Z","latitude":23.834,"longitude":90.419}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Public Integration API"],"security":[{"apiKeyAuth":[]}],"summary":"Get Overspeed Event Logs & Violations"}},"/api/stream/positions":{"get":{"description":"Opens a persistent, unbuffered Server-Sent Events (SSE) connection that streams real-time GPS coordinates, speed, heading, and ignition states for all devices in the authenticated organization.\n \n### Connection Details\n- Streams both fast raw gateway pings and enriched worker telemetry (fuel level, battery, temperature).\n- Keeps the connection alive with automatic 15-second heartbeat comments (`: ping`).\n- Accepts Bearer token via `Authorization` header or `?token=` query parameter (compatible with native browser `EventSource`).","parameters":[{"name":"imeis","in":"query","schema":{"type":"string"}},{"name":"token","in":"query","schema":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"required":false,"description":"JWT Bearer token (for browser EventSource which cannot set custom HTTP headers)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Text/event-stream real-time telemetry stream.","content":{"text/event-stream":{"schema":{"type":"string"},"example":"data: {\"imei\":\"864540081293581\",\"lat\":23.8103,\"lon\":90.4125,\"speed\":48,\"ignition\":true,\"time\":\"2026-10-01T10:20:15Z\"}\n\n"}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"429":{"description":"Too Many Requests"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Streams"],"summary":"Live Fleet Positions Stream (Server-Sent Events / SSE)","security":[{"bearerAuth":[]}]}},"/api/stream/positions/{imei}":{"get":{"description":"Streams high-frequency real-time updates for an individual vehicle. Ideal for active turn-by-turn map views, vehicle chase mode, or live dashboard gauges.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit target device IMEI"},{"name":"token","in":"query","schema":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"description":"JWT Bearer token for EventSource authentication"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Continuous SSE stream of telemetry points for the single device.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"429":{"description":"Too Many Requests"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Streams"],"summary":"Single Device Live Telemetry Stream (SSE)","security":[{"bearerAuth":[]}]}},"/api/stream/alerts":{"get":{"description":"Pushes instant notifications whenever a rule is triggered across the fleet (overspeed, geofence enter/exit, SOS panic button, towing detection, power disconnection, or harsh driving).","parameters":[{"name":"token","in":"query","schema":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"description":"JWT Bearer token for EventSource authentication"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Stream of real-time alert events.","content":{"text/event-stream":{"schema":{"type":"string"},"example":"data: {\"id\":\"a8b3...\",\"type\":\"overspeed\",\"vehicle_name\":\"Toyota Allion\",\"speed\":92,\"speed_limit\":80,\"timestamp\":\"2026-10-01T10:21:00Z\"}\n\n"}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"429":{"description":"Too Many Requests"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Streams"],"summary":"Live Fleet Alert Events Stream (SSE)","security":[{"bearerAuth":[]}]}},"/api/stream/chat/{roomId}":{"get":{"description":"Streams instant messages between dispatchers, fleet operators, and assigned drivers inside a specific conversation room.","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string","example":"room-14-dispatch"},"description":"Chat conversation room UUID or identifier"},{"name":"token","in":"query","schema":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"description":"JWT Bearer token for EventSource authentication"}],"responses":{"200":{"description":"Chat messages text/event-stream.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"429":{"description":"Too Many Requests"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Streams"],"summary":"Real-Time Dispatch Chat Stream (SSE)","security":[{"bearerAuth":[]}]}},"/api/stream/status":{"get":{"description":"Provides real-time health statistics of the streaming cluster, including number of active client connections and Redis subscriber status.","parameters":[],"responses":{"200":{"description":"Active streaming connection metrics.","content":{"application/json":{"example":{"activeConnections":18,"maxAllowedPerUser":25,"redisChannels":["vega:live","vega:stream","vega:alert"],"timestamp":"2026-10-01T10:22:00Z"}}}},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"}},"tags":["Streams"],"summary":"Get SSE Streaming Server Health & Connection Metrics","security":[{"bearerAuth":[]}]}},"/api/users/me/profile":{"get":{"description":"Returns current user account details, assigned roles, organization UUID, avatar URL, and effective RBAC permissions bitmask.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Current user profile.","content":{"application/json":{"example":{"success":true,"data":{"id":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","name":"Fleet Manager","email":"dispatcher@xeekar.com","role":"admin","org_id":"90e544ce-d284-48f0-b8d4-63fcb001a1c5","timezone":"Asia/Dhaka","isPlatformAdmin":false}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Authenticated User Profile & Active Permissions","security":[{"bearerAuth":[]}]},"put":{"description":"Allows authenticated user to update their display name, phone number, or avatar.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Profile updated."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Fleet Operations Manager"},"phone":{"type":"string","example":"+8801712345678"}}},"example":{"name":"Fleet Operations Manager","phone":"+8801712345678"}}}},"tags":["Users"],"summary":"Update Personal Profile Details","security":[{"bearerAuth":[]}]}},"/api/users/me/timezone":{"put":{"description":"Updates and overwrites properties of the target Users Me Timezone.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"timezone":{"example":"any"}}}}}},"tags":["Users"],"summary":"Update Users Me Timezone"}},"/api/users/me/preferences":{"get":{"description":"Retrieves a paginated list of Users Me Preferences accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Users Me Preferences"},"put":{"description":"Updates and overwrites properties of the target Users Me Preferences.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Update Users Me Preferences"}},"/api/users/me/notification-preferences":{"get":{"description":"Retrieves a paginated list of Users Me Notification-preferences accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Users Me Notification-preferences"},"put":{"description":"Updates and overwrites properties of the target Users Me Notification-preferences.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"example":"any"},"sound_enabled":{"example":"any"},"sound_mode":{"example":"any"},"desktop_enabled":{"example":"any"},"push_enabled":{"example":"any"},"volume":{"example":"any"},"muted_rule_ids":{"example":"any"},"muted_device_alerts":{"example":"any"},"dnd_enabled":{"example":"any"},"dnd_start":{"example":"any"},"dnd_end":{"example":"any"},"dnd_timezone":{"example":"any"},"admin_fleet_scope":{"example":"any"},"fleet_routine_alerts":{"example":"any"}}}}}},"tags":["Users"],"summary":"Update Users Me Notification-preferences"}},"/api/users/me/sessions":{"get":{"description":"Retrieves a paginated list of Users Me Sessions accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Users Me Sessions"},"delete":{"description":"Permanently removes or unlinks the target Users Me Sessions from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Delete Users Me Sessions"}},"/api/users/me/account":{"delete":{"description":"Permanently removes or unlinks the target Users Me Account from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Delete Users Me Account"}},"/api/users/fcm-token":{"post":{"description":"Registers or updates the mobile device or web browser push notification token to receive real-time alerts.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"FCM push token registered."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Firebase device push registration token","example":"f87a9bc2...43f"},"platform":{"type":"string","enum":["android","ios","web"],"example":"android"}}},"example":{"token":"f87a9bc2...43f","platform":"android"}}}},"tags":["Users"],"summary":"Register Firebase Cloud Messaging (FCM) Push Token","security":[{"bearerAuth":[]}]},"delete":{"description":"Permanently removes or unlinks the target Users Fcm-token from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"example":"any"}}}}}},"tags":["Users"],"summary":"Delete Users Fcm-token"}},"/api/users":{"get":{"description":"Retrieves all users enrolled in the tenant organization, their roles, active status, and last login timestamps.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of users."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"List Organization Users & Sub-Accounts","security":[{"bearerAuth":[]}]},"post":{"description":"Provisions a new user account under the organization and sends activation credentials.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"User created successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password","name"],"properties":{"email":{"type":"string","format":"email","example":"ops2@company.com"},"password":{"type":"string","minLength":4,"maxLength":10,"description":"User password (4 to 10 characters)","example":"Temp1234"},"name":{"type":"string","example":"Assistant Dispatcher"},"role":{"type":"string","enum":["admin","manager","viewer","driver","dispatcher"],"description":"Friendly role name (auto-mapped to tenant role ID)","example":"manager"},"role_id":{"type":"string","format":"uuid","description":"Tenant role UUID (provide either role or role_id)","example":"1059166a-54ee-4ced-aa7e-c36053f59a24"},"phone":{"type":"string","example":"+8801712345678"}}},"example":{"email":"ops2@company.com","password":"Temp1234","name":"Assistant Dispatcher","role":"manager"}}}},"tags":["Users"],"summary":"Create / Invite New User","security":[{"bearerAuth":[]}]}},"/api/users/bulk-import":{"post":{"description":"Provisions, dispatches, or creates a new Users Bulk-import in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"users":{"example":"any"}}}}}},"tags":["Users"],"summary":"Create or Trigger Users Bulk-import"}},"/api/users/{id}":{"put":{"description":"Updates an existing user account under the organization, including display name, contact phone, email, assigned role, or active status.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","format":"uuid"},"description":"Unique UUID of the user account"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"User updated successfully.","content":{"application/json":{"example":{"success":true,"message":"User updated successfully"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Customer Support Lead"},"email":{"type":"string","format":"email","example":"lead@company.com"},"phone":{"type":"string","example":"+8801700000000"},"role":{"type":"string","enum":["admin","manager","viewer","driver","dispatcher"],"description":"Friendly role name","example":"manager"},"role_id":{"type":"string","format":"uuid","example":"1059166a-54ee-4ced-aa7e-c36053f59a24"},"password":{"type":"string","minLength":4,"maxLength":10,"description":"New password (4 to 10 characters)","example":"NewPass1"},"active":{"type":"boolean","example":true}}},"example":{"name":"Customer Support Lead","phone":"+8801700000000","active":true}}}},"tags":["Users"],"summary":"Update User Profile, Role, or Status","security":[{"bearerAuth":[]}]},"delete":{"description":"Permanently removes a user account from the organization and revokes all vehicle assignments and active sessions.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","format":"uuid"},"description":"Unique UUID of the user account to delete"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"User deleted successfully.","content":{"application/json":{"example":{"success":true,"message":"User deleted successfully"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Delete User Account","security":[{"bearerAuth":[]}]}},"/api/users/{id}/status":{"patch":{"description":"Toggles a user between active and suspended states. Suspended users cannot log in or receive notifications. Ideal for automated ERP billing suspension.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","format":"uuid"},"description":"Unique UUID of the user account"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"User status updated successfully.","content":{"application/json":{"example":{"success":true,"data":{"id":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","email":"customer@example.com","name":"Customer Name","active":false}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["active"],"properties":{"active":{"type":"boolean","description":"true to activate, false to suspend","example":false}}},"example":{"active":false}}}},"tags":["Users"],"summary":"Activate or Suspend User Account","security":[{"bearerAuth":[]}]}},"/api/users/{id}/reveal-password":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Users Id Reveal-password within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Users Id Reveal-password"}},"/api/users/{id}/set-password":{"post":{"description":"Overrides and resets a user password directly without requiring the old password. Designed for ERP/Admin onboarding.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","format":"uuid"},"description":"Unique UUID of the user account"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Password updated successfully.","content":{"application/json":{"example":{"success":true,"message":"Password updated successfully"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["password"],"properties":{"password":{"type":"string","minLength":4,"maxLength":10,"example":"Pass1234"}}},"example":{"password":"Pass1234"}}}},"tags":["Users"],"summary":"Admin Set User Password","security":[{"bearerAuth":[]}]}},"/api/users/{id}/fleet-assignments":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Users Id Fleet-assignments within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Users Id Fleet-assignments"},"put":{"description":"Updates and overwrites properties of the target Users Id Fleet-assignments.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fleet_ids":{"example":"any"}}}}}},"tags":["Users"],"summary":"Update Users Id Fleet-assignments"}},"/api/users/{id}/device-assignments":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Users Id Device-assignments within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Users Id Device-assignments"},"put":{"description":"Updates and overwrites properties of the target Users Id Device-assignments.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_imeis":{"example":"any"}}}}}},"tags":["Users"],"summary":"Update Users Id Device-assignments"},"post":{"description":"Provisions, dispatches, or creates a new Users Id Device-assignments in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_imeis":{"example":"any"}}}}}},"tags":["Users"],"summary":"Create or Trigger Users Id Device-assignments"},"delete":{"description":"Permanently removes or unlinks the target Users Id Device-assignments from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_imeis":{"example":"any"}}}}}},"tags":["Users"],"summary":"Delete Users Id Device-assignments"}},"/api/users/me/device-assignments":{"get":{"description":"Retrieves a paginated list of Users Me Device-assignments accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Get Users Me Device-assignments"},"put":{"description":"Updates and overwrites properties of the target Users Me Device-assignments.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_imeis":{"example":"any"}}}}}},"tags":["Users"],"summary":"Update Users Me Device-assignments"}},"/api/users/{id}/impersonate":{"post":{"description":"Provisions, dispatches, or creates a new Users Id Impersonate in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Users"],"summary":"Create or Trigger Users Id Impersonate"}},"/api/org/hub/destinations":{"get":{"description":"Retrieves a paginated list of Org Hub Destinations accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Hub Destinations"},"post":{"description":"Provisions, dispatches, or creates a new Org Hub Destinations in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"active":{"example":"any"},"url":{"example":"any"},"authHeader":{"example":"any"},"format":{"example":"any"},"batchSize":{"example":"any"},"flushIntervalMs":{"example":"any"},"vendorConfig":{"example":"any"},"brokerUrl":{"example":"any"},"topic":{"example":"any"},"username":{"example":"any"},"password":{"example":"any"},"host":{"example":"any"},"port":{"example":"any"},"device_scope":{"example":"any"},"device_imeis":{"example":"any"},"user_id":{"example":"any"},"user_ids":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Create or Trigger Org Hub Destinations"}},"/api/org/hub/providers":{"get":{"description":"Retrieves a paginated list of Org Hub Providers accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Hub Providers"}},"/api/org/hub/providers/{providerKey}":{"put":{"description":"Updates and overwrites properties of the target Org Hub Providers ProviderKey.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"providerKey","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"endpoint_url":{"example":"any"},"auth_type":{"example":"any"},"config":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Hub Providers ProviderKey"}},"/api/org/hub/destinations/{id}":{"put":{"description":"Updates and overwrites properties of the target Org Hub Destinations Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"active":{"example":"any"},"url":{"example":"any"},"authHeader":{"example":"any"},"format":{"example":"any"},"batchSize":{"example":"any"},"flushIntervalMs":{"example":"any"},"vendorConfig":{"example":"any"},"brokerUrl":{"example":"any"},"topic":{"example":"any"},"username":{"example":"any"},"password":{"example":"any"},"host":{"example":"any"},"port":{"example":"any"},"device_scope":{"example":"any"},"device_imeis":{"example":"any"},"user_id":{"example":"any"},"user_ids":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Hub Destinations Id"},"delete":{"description":"Permanently removes or unlinks the target Org Hub Destinations Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Delete Org Hub Destinations Id"}},"/api/org/hub/destinations/{id}/devices":{"put":{"description":"Updates and overwrites properties of the target Org Hub Destinations Id Devices.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_scope":{"example":"any"},"device_imeis":{"example":"any"},"user_id":{"example":"any"},"user_ids":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Hub Destinations Id Devices"}},"/api/org/hub/destinations/{id}/test":{"post":{"description":"Provisions, dispatches, or creates a new Org Hub Destinations Id Test in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imei":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Create or Trigger Org Hub Destinations Id Test"}},"/api/org/hub/toggle-mode":{"put":{"description":"Updates and overwrites properties of the target Org Hub Toggle-mode.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"storage_enabled":{"example":"any"},"forwarding_enabled":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Hub Toggle-mode"}},"/api/org/hub/scope":{"put":{"description":"Updates and overwrites properties of the target Org Hub Scope.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"example":"any"},"org_wide":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Hub Scope"}},"/api/org/hub/devices":{"get":{"description":"Retrieves a paginated list of Org Hub Devices accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Hub Devices"},"put":{"description":"Updates and overwrites properties of the target Org Hub Devices.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Hub Devices"}},"/api/org/hub/destinations/{id}/logs":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Org Hub Destinations Id Logs within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Hub Destinations Id Logs"},"delete":{"description":"Permanently removes or unlinks the target Org Hub Destinations Id Logs from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Delete Org Hub Destinations Id Logs"}},"/api/org":{"get":{"description":"Retrieves tenant organization profile, company name, address, default map coordinates, custom logo URL, coin balance, and active telemetry limits.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Organization settings.","content":{"application/json":{"example":{"success":true,"data":{"id":"90e544ce-d284-48f0-b8d4-63fcb001a1c5","name":"Xeekar Corp","logo_url":"https://cdn.vegagps.com/logos/xeekar.png","timezone":"Asia/Dhaka","currency":"BDT","coin_balance":1450,"speed_unit":"km/h"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Current Organization Settings & White-Label Config","security":[{"bearerAuth":[]}]},"put":{"description":"Updates company name, default map center, address, or notification settings.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Organization settings updated."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Xeekar Logistics Ltd."},"timezone":{"type":"string","example":"Asia/Dhaka"},"currency":{"type":"string","example":"BDT"}}},"example":{"name":"Xeekar Logistics Ltd.","timezone":"Asia/Dhaka"}}}},"tags":["Organizations"],"summary":"Update Organization Settings","security":[{"bearerAuth":[]}]}},"/api/org/upload-logo":{"post":{"description":"Provisions, dispatches, or creates a new Org Upload-logo in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Create or Trigger Org Upload-logo"}},"/api/org/connectors":{"get":{"description":"Retrieves a paginated list of Org Connectors accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Connectors"},"post":{"description":"Provisions, dispatches, or creates a new Org Connectors in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"example":"any"},"name":{"example":"any"},"config":{"example":"any"},"is_enabled":{"example":"any"},"is_default":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Create or Trigger Org Connectors"}},"/api/org/connectors/{id}":{"put":{"description":"Updates and overwrites properties of the target Org Connectors Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"config":{"example":"any"},"is_enabled":{"example":"any"},"is_default":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Connectors Id"},"delete":{"description":"Permanently removes or unlinks the target Org Connectors Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Delete Org Connectors Id"}},"/api/org/connectors/{id}/test":{"post":{"description":"Provisions, dispatches, or creates a new Org Connectors Id Test in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"test_recipient":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Create or Trigger Org Connectors Id Test"}},"/api/org/push-credentials":{"get":{"description":"Retrieves a paginated list of Org Push-credentials accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Push-credentials"},"put":{"description":"Updates and overwrites properties of the target Org Push-credentials.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"credentials":{"example":"any"},"project_id":{"example":"any"},"private_key":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Push-credentials"},"delete":{"description":"Permanently removes or unlinks the target Org Push-credentials from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Delete Org Push-credentials"}},"/api/org/push-credentials/test":{"post":{"description":"Provisions, dispatches, or creates a new Org Push-credentials Test in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"example":"any"},"title":{"example":"any"},"body":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Create or Trigger Org Push-credentials Test"}},"/api/org/children":{"get":{"description":"Retrieves a paginated list of Org Children accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Children"},"post":{"description":"Provisions, dispatches, or creates a new Org Children in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"plan":{"example":"any"},"adminEmail":{"example":"any"},"adminName":{"example":"any"},"adminPassword":{"example":"any"},"type":{"example":"any"},"slug":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Create or Trigger Org Children"}},"/api/org/tree":{"get":{"description":"Returns complete recursive organization hierarchy tree for reseller networks and enterprise holding groups.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Hierarchical tree of organizations."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Multi-Tenant Reseller / Sub-Organization Hierarchy Tree","security":[{"bearerAuth":[]}]}},"/api/org/children/{id}":{"put":{"description":"Updates and overwrites properties of the target Org Children Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"plan":{"example":"any"},"type":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Children Id"},"delete":{"description":"Permanently removes or unlinks the target Org Children Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Delete Org Children Id"}},"/api/org/children/{id}/status":{"patch":{"description":"Applies partial field modifications to the target Org Children Id Status.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Modify Org Children Id Status"}},"/api/org/children/{id}/users":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Org Children Id Users within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Children Id Users"}},"/api/org/children/{id}/branch":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Org Children Id Branch within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Children Id Branch"}},"/api/org/children/{orgId}/impersonate":{"post":{"description":"Provisions, dispatches, or creates a new Org Children OrgId Impersonate in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Create or Trigger Org Children OrgId Impersonate"}},"/api/org/exit-impersonation":{"post":{"description":"Provisions, dispatches, or creates a new Org Exit-impersonation in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Create or Trigger Org Exit-impersonation"}},"/api/org/api-keys":{"get":{"description":"Retrieves a paginated list of Org Api-keys accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Api-keys"},"post":{"description":"Provisions, dispatches, or creates a new Org Api-keys in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"expires_in":{"example":"any"},"allowed_vehicle_ids":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Create or Trigger Org Api-keys"}},"/api/org/api-keys/{id}":{"put":{"description":"Updates and overwrites properties of the target Org Api-keys Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"allowed_vehicle_ids":{"example":"any"}}}}}},"tags":["Organizations"],"summary":"Update Org Api-keys Id"},"delete":{"description":"Permanently removes or unlinks the target Org Api-keys Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Delete Org Api-keys Id"}},"/api/org/shareable":{"get":{"description":"Retrieves a paginated list of Org Shareable accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Org Shareable"}},"/api/analytics/overview":{"get":{"description":"Retrieves high-level executive fleet metrics: total fleet count, currently moving, idling, parked, offline, total kilometers driven today, and fuel consumed.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Executive dashboard KPIs.","content":{"application/json":{"example":{"success":true,"data":{"total_vehicles":42,"moving":18,"idling":4,"stopped":16,"offline":4,"total_km_today":3482.4,"fuel_consumed_liters_today":412.5,"active_alerts_count":3}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Fleet Operations Dashboard KPI Overview","security":[{"bearerAuth":[]}]}},"/api/analytics/charts":{"get":{"description":"Retrieves a paginated list of Analytics Charts accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Charts"}},"/api/analytics/trend":{"get":{"description":"Retrieves a paginated list of Analytics Trend accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Trend"}},"/api/analytics/drivers":{"get":{"description":"Calculates safety scorecards across all assigned fleet drivers, grading harsh braking, rapid acceleration, excessive speeding, and engine idling hours.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Ranked driver performance leaderboard."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Driver Safety & Performance Leaderboard","security":[{"bearerAuth":[]}]}},"/api/analytics/device-kpis":{"get":{"description":"Retrieves a paginated list of Analytics Device-kpis accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Device-kpis"}},"/api/analytics/fleet-health":{"get":{"description":"Retrieves a paginated list of Analytics Fleet-health accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Fleet-health"}},"/api/analytics/km-summary":{"get":{"description":"Retrieves a paginated list of Analytics Km-summary accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Km-summary"}},"/api/analytics/utilization":{"get":{"description":"Retrieves a paginated list of Analytics Utilization accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Utilization"}},"/api/analytics/utilization-trend":{"get":{"description":"Retrieves a paginated list of Analytics Utilization-trend accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Utilization-trend"}},"/api/analytics/heatmap":{"get":{"description":"Retrieves a paginated list of Analytics Heatmap accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Heatmap"}},"/api/analytics/fuel":{"get":{"description":"Returns aggregate fuel statistics, daily fleet fuel drain curve, detected refueling transactions, and potential fuel siphon/theft incidents.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"from","in":"query","description":"Start date","schema":{"type":"string","example":"2026-10-01"}},{"name":"to","in":"query","description":"End date","schema":{"type":"string","example":"2026-10-01"}}],"responses":{"200":{"description":"Fuel consumption and incident statistics."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Fleet-Wide Fuel Efficiency & Anomaly Analytics","security":[{"bearerAuth":[]}]}},"/api/analytics/fuel/morning-check":{"get":{"description":"Exception-first morning dispatch dashboard comparing fuel levels at evening park-up vs morning ignition. Flags vehicles that experienced overnight fuel drops while parked in yard or transit.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Morning fuel triage report with flagged theft drops.","content":{"application/json":{"example":{"success":true,"data":{"checked_vehicles":42,"overnight_thefts_detected":1,"items":[{"imei":"864540081293581","vehicle_name":"Toyota Allion 2024","park_time":"2026-09-30T22:00:00Z","park_fuel_liters":52,"morning_fuel_liters":38,"drop_liters":14,"flagged_as_theft":true}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Morning Fuel Check & Overnight Theft Triage","security":[{"bearerAuth":[]}]}},"/api/analytics/fuel/device/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Analytics Fuel Device Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Fuel Device Imei"}},"/api/analytics/fuel/events/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Analytics Fuel Events Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Fuel Events Imei"}},"/api/analytics/fuel/events/{id}/verify":{"patch":{"description":"Applies partial field modifications to the target Analytics Fuel Events Id Verify.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Modify Analytics Fuel Events Id Verify"}},"/api/analytics/fuel/sections/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Analytics Fuel Sections Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Fuel Sections Imei"}},"/api/analytics/fuel/raw/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Analytics Fuel Raw Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Fuel Raw Imei"}},"/api/analytics/temperature":{"get":{"description":"Monitors reefer cargo temperature trends across cold-chain fleet, flagging temperature excursions exceeding compliance thresholds (e.g. pharmaceuticals, frozen goods).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Cold chain compliance metrics and active excursion alerts."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Cold-Chain Reefer Cargo Temperature Analytics","security":[{"bearerAuth":[]}]}},"/api/analytics/temperature/device/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Analytics Temperature Device Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Temperature Device Imei"}},"/api/analytics/temperature/excursions":{"get":{"description":"Retrieves a paginated list of Analytics Temperature Excursions accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Temperature Excursions"}},"/api/analytics/temperature/excursions/{id}/acknowledge":{"post":{"description":"Provisions, dispatches, or creates a new Analytics Temperature Excursions Id Acknowledge in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Create or Trigger Analytics Temperature Excursions Id Acknowledge"}},"/api/analytics/temperature/trips":{"get":{"description":"Retrieves a paginated list of Analytics Temperature Trips accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Temperature Trips"}},"/api/analytics/temperature/trips/{id}/curve":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Analytics Temperature Trips Id Curve within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Temperature Trips Id Curve"}},"/api/analytics/driver-scores":{"get":{"description":"Retrieves a paginated list of Analytics Driver-scores accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Analytics"],"summary":"Get Analytics Driver-scores"}},"/api/devices/exists/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Exists Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Exists Imei"}},"/api/devices":{"get":{"summary":"List Fleet Devices with Status & Filtering","description":"Retrieves a paginated list of all GPS trackers and vehicles accessible to the authenticated user's organization scope.\n\n### Filtering & Search\n- Filter by motion state: `status=moving`, `status=idle`, `status=stopped`, or `status=offline`.\n- Filter by fleet assignment: `fleet_id=123`.\n- Full-text search across vehicle name, license plate, or device IMEI.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","description":"Page number for pagination (starts at 1)","schema":{"type":"integer","default":1,"example":1}},{"name":"limit","in":"query","description":"Number of device records per page (max 1000)","schema":{"type":"integer","default":50,"example":25}},{"name":"search","in":"query","description":"Case-insensitive search matching vehicle name, plate number, or IMEI","schema":{"type":"string","example":"Allion"}},{"name":"status","in":"query","description":"Filter by current vehicle operational state","schema":{"type":"string","example":"moving","enum":["moving","idle","stopped","offline"]}},{"name":"fleet_id","in":"query","description":"Filter by fleet or sub-group identifier","schema":{"type":"string","example":"14"}}],"responses":{"200":{"description":"List of devices with pagination metadata.","content":{"application/json":{"example":{"success":true,"data":[{"imei":"864540081293581","name":"Toyota Allion 2024","plate_number":"DHK-METRO-GA-11-2041","model":"GT06Pro","vehicle_type":"car","fleet_id":14,"fleet_name":"Executive Fleet","online":true,"engine_on":true,"motion_state":"moving","speed":48,"lat":23.8103,"lon":90.4125,"last_seen":"2026-10-01T10:20:00Z","speed_limit":80}],"pagination":{"page":1,"limit":25,"total":42,"totalPages":2}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"security":[{"bearerAuth":[]}]},"post":{"summary":"Register New Tracking Device","description":"Provisions a new GPS tracking hardware device into the organization inventory.\n\n### Device Onboarding\nUpon registration, the device is immediately assigned to the tenant organization. The device IMEI must be unique across the platform.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Device registered successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"402":{"description":"Insufficient coin balance"},"403":{"description":"Forbidden"},"409":{"description":"Device with this IMEI is already registered."},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imei","name"],"properties":{"imei":{"type":"string","description":"15-digit unique hardware IMEI number","example":"864540081293581"},"name":{"type":"string","description":"Friendly vehicle or asset name","example":"Toyota Allion 2024"},"model":{"type":"string","description":"Hardware protocol/model identifier (e.g. GT06, Teltonika, Jimi, Coban)","example":"GT06Pro"},"vehicle_type":{"type":"string","enum":["car","truck","bus","motorcycle","van","tractor","trailer","ship","lock"],"example":"car"},"plate_number":{"type":"string","description":"Vehicle government license plate registration number","example":"DHK-METRO-GA-11-2041"},"fleet_id":{"type":"integer","description":"Optional fleet group assignment ID","example":14},"sim_number":{"type":"string","description":"Cellular SIM MSISDN phone number in device","example":"+8801712345678"},"speed_limit":{"type":"number","description":"Overspeed alert threshold in km/h","example":80},"tank_capacity":{"type":"number","description":"Total fuel tank capacity in liters (for fuel sensor calibration)","example":60}}},"example":{"imei":"864540081293581","name":"Toyota Allion 2024","model":"GT06Pro","vehicle_type":"car","plate_number":"DHK-METRO-GA-11-2041","speed_limit":80,"tank_capacity":60}}}},"tags":["Devices"],"security":[{"bearerAuth":[]}]}},"/api/devices/video":{"get":{"description":"Retrieves a paginated list of Devices Video accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Video"}},"/api/devices/positions":{"get":{"description":"High-frequency polling endpoint used by live tracking maps to retrieve updated coordinates, speed, heading, and motion state since a given timestamp.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"since","in":"query","description":"ISO-8601 UTC timestamp to receive only devices updated after this moment","schema":{"type":"string","example":"2026-10-01T10:15:00Z"}}],"responses":{"200":{"description":"Array of updated vehicle positions and states."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Real-Time Delta Positions for Tracking Map","security":[{"bearerAuth":[]}]}},"/api/devices/expiring":{"get":{"description":"Retrieves devices whose telematics service subscriptions will expire within the specified timeframe (default 30 days), facilitating proactive renewal outreach.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"days","in":"query","description":"Lookahead threshold in days (default: 30)","schema":{"type":"integer","default":30,"example":30}}],"responses":{"200":{"description":"List of expiring devices and days remaining."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"List Devices with Expiring Subscriptions (Next 30 Days)","security":[{"bearerAuth":[]}]}},"/api/devices/health":{"get":{"description":"Evaluates device reporting consistency, GPS fix validity, cellular signal quality (CSQ), and battery level across the fleet to highlight unhealthy hardware.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Fleet health scores and connectivity summary."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Fleet Telemetry Health & Connectivity Diagnostics","security":[{"bearerAuth":[]}]}},"/api/devices/personas":{"get":{"description":"Retrieves a paginated list of Devices Personas accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Personas"}},"/api/devices/models":{"get":{"description":"Retrieves a paginated list of Devices Models accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Models"},"post":{"description":"Provisions, dispatches, or creates a new Devices Models in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Create or Trigger Devices Models"}},"/api/devices/models/{id}":{"put":{"description":"Updates and overwrites properties of the target Devices Models Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Update Devices Models Id"},"delete":{"description":"Permanently removes or unlinks the target Devices Models Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Delete Devices Models Id"}},"/api/devices/transport-models":{"get":{"description":"Retrieves a paginated list of Devices Transport-models accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Transport-models"},"post":{"description":"Provisions, dispatches, or creates a new Devices Transport-models in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Create or Trigger Devices Transport-models"}},"/api/devices/assignment-counts":{"get":{"description":"Retrieves a paginated list of Devices Assignment-counts accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Assignment-counts"}},"/api/devices/{imei}":{"get":{"description":"Retrieves full configuration, current telemetry, sensor port mappings, assigned driver, odometer, engine hours, and subscription validity for a specific tracker.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Complete device profile and telemetry state.","content":{"application/json":{"example":{"success":true,"data":{"imei":"864540081293581","name":"Toyota Allion 2024","plate_number":"DHK-METRO-GA-11-2041","model":"GT06Pro","vehicle_type":"car","engine_on":true,"speed":48,"lat":23.8103,"lon":90.4125,"odometer_km":18450.2,"total_engine_hours":482.5,"speed_limit":80,"tank_capacity":60,"battery_voltage":13.8,"battery_percent":100,"subscription_end":"2027-10-01T00:00:00Z"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Device not found."},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Detailed Single Device Profile & Hardware Telemetry","security":[{"bearerAuth":[]}]},"put":{"description":"Updates vehicle metadata, plate number, assigned driver, speed limits, or fuel tank capacity.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Device profile updated successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Update Device Settings, Plate & Calibration","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Toyota Allion VIP"},"plate_number":{"type":"string","example":"DHK-METRO-GA-11-2041"},"speed_limit":{"type":"number","example":80},"tank_capacity":{"type":"number","example":60},"fleet_id":{"type":"integer","example":14}}},"example":{"name":"Toyota Allion VIP","plate_number":"DHK-METRO-GA-11-2041","speed_limit":80,"tank_capacity":60}}}}},"delete":{"description":"Deletes a device from the organization. Historical positions and trips are archived.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Device successfully removed."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Delete or Unregister Device","security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/daily-stats":{"get":{"tags":["Devices"],"summary":"Get Daily Mileage & Engine Hours (Weekly Mobile Overview)","description":"Retrieves a continuous, zero-filled daily time series of distance traveled, engine hours, driving time, idle duration, stop duration, and trip count.\n \n### Zero-Filling Guarantee\n- Ensures every single calendar date within the requested range has an entry, even if the vehicle had battery disconnected or was offline.\n- Designed specifically for 7-day mobile overview charts (*Travel Overview* and *Engine Hours*).","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"from","description":"Start date in YYYY-MM-DD format (defaults to 6 days ago for a 7-day window)","required":false,"example":"2026-09-26","in":"query","schema":{"type":"string","example":"2026-09-26"}},{"name":"to","description":"End date in YYYY-MM-DD format (defaults to today)","required":false,"example":"2026-10-02","in":"query","schema":{"type":"string","example":"2026-10-02"}},{"name":"timezone","description":"IANA timezone for day boundaries (defaults to organization timezone or Asia/Dhaka)","required":false,"in":"query","schema":{"type":"string","example":"Asia/Dhaka"}},{"name":"format","in":"query","description":"Output format: \"human\" for formatted unit strings (e.g. \"3.69 km\", \"45m\", \"23h 45m\") or \"raw\" for pure decimals (defaults to human)","schema":{"type":"string","enum":["human","raw"],"default":"human"}}],"responses":{"200":{"description":"Daily metrics successfully retrieved"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/installation-status":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Installation-status within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Imei Installation-status"}},"/api/devices/{imei}/current-trip":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Current-trip within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Imei Current-trip"}},"/api/devices/{imei}/dtc":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Dtc within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Imei Dtc"}},"/api/devices/{imei}/audit-logs":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Audit-logs within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Get Devices Imei Audit-logs"}},"/api/devices/{imei}/assigned-users":{"get":{"description":"Retrieves all client user profiles currently granted access to view and monitor this vehicle.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of assigned users.","content":{"application/json":{"example":{"success":true,"data":[{"id":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","name":"Customer Name","email":"customer@example.com","role":"viewer"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"List Users Assigned to Device","security":[{"bearerAuth":[]}]},"put":{"description":"Assigns or replaces the list of client users who are permitted to track this vehicle. Replaces all existing user assignments for this vehicle with the provided list of user IDs.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Device user assignments updated.","content":{"application/json":{"example":{"success":true,"message":"Device users updated successfully"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_ids"],"properties":{"user_ids":{"type":"array","items":{"type":"string","format":"uuid","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b"},"description":"Array of user UUIDs who should have access to this device"}}},"example":{"user_ids":["c1f7b76e-347f-44de-9e5c-0c153b664d4b"]}}}},"tags":["Devices"],"summary":"Assign / Replace Users for Device","security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/duplicate":{"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Duplicate in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Create or Trigger Devices Imei Duplicate"}},"/api/devices/{imei}/fleet":{"put":{"description":"Updates and overwrites properties of the target Devices Imei Fleet.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Update Devices Imei Fleet"}},"/api/devices/{imei}/sensor-setup-complete":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Sensor-setup-complete.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Modify Devices Imei Sensor-setup-complete"}},"/api/devices/{imei}/subscription":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Subscription.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Modify Devices Imei Subscription"}},"/api/devices/{imei}/renew":{"post":{"description":"Extends the active telematics subscription for a device by deducting prepaid coins from the organization balance. 1 coin extends subscription by 12 months (365 days). If expired, the new expiry starts from today; if still active, 12 months are appended to current expiration date.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Subscription extended successfully.","content":{"application/json":{"example":{"success":true,"message":"Subscription extended by 12 months","data":{"imei":"864540081293581","subscription_end":"2027-10-05T00:00:00.000Z","coins_deducted":1,"remaining_balance":1449}}}}},"401":{"description":"Unauthorized"},"402":{"description":"Insufficient coin balance in organization."},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Renew Device Telematics Subscription (Coins)","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"coins":{"type":"integer","default":1,"example":1,"description":"Number of prepaid coins to consume (1 coin = 12 months)"}}},"example":{"coins":1}}}}}},"/api/devices/{imei}/status":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Status.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Modify Devices Imei Status"}},"/api/devices/{imei}/speed-limit":{"patch":{"description":"Sets the maximum permissible speed in km/h for the vehicle. Speeds exceeding this threshold trigger automated alerts.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Speed limit threshold updated."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Configure Vehicle Overspeed Alert Threshold","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["speed_limit"],"properties":{"speed_limit":{"type":"number","example":80}}},"example":{"speed_limit":80}}}}}},"/api/devices/{imei}/shares":{"get":{"description":"Retrieves active temporary tracking links or cross-organization device shares created for this tracker.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of active location shares."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"List Public / Cross-Tenant Location Shares for Device","security":[{"bearerAuth":[]}]},"post":{"description":"Creates a time-expiring public URL (with optional PIN or password) allowing third-party customers or recipients to track vehicle arrival in real time.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Share link created with public token and URL."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Generate Temporary Public Live Tracking Link","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expires_in_hours"],"properties":{"expires_in_hours":{"type":"integer","default":24,"example":24},"recipient_name":{"type":"string","example":"Customer Acme Corp"}}},"example":{"expires_in_hours":24,"recipient_name":"Customer Acme Corp"}}}}}},"/api/devices/{imei}/shares/{shareId}":{"delete":{"description":"Permanently removes or unlinks the target Devices Imei Shares ShareId from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"shareId","in":"path","required":true,"schema":{"type":"string","example":"share_94fb21a"},"description":"Public location share token or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Delete Devices Imei Shares ShareId"}},"/api/devices/{imei}/change-imei":{"patch":{"description":"Swaps the underlying GPS tracker hardware IMEI while preserving the vehicle name, plate number, historical trips, sensors, and maintenance records intact.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Current 15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Hardware swapped successfully."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Devices"],"summary":"Swap / Replace Physical Device Hardware (Preserve Vehicle Data)","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["new_imei"],"properties":{"new_imei":{"type":"string","example":"865167047241865"}}},"example":{"new_imei":"865167047241865"}}}}}},"/api/devices/{imei}/sensors":{"get":{"description":"Retrieves all active analog, digital, RS485, and BLE telemetry sensors attached to a specific tracker, including fuel probes, cargo temperature probes, and door inputs.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"showHidden","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Array of attached device sensors and calibration settings.","content":{"application/json":{"example":{"success":true,"data":[{"id":1,"device_id":"864540081293581","name":"Main Fuel Tank","port":"fuel_level","sensor_type":"fuel","unit":"L","value":48.5,"calibration_points":[{"raw":0,"val":0},{"raw":4095,"val":60}]}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"List Configured Physical & Virtual Sensors for Device","security":[{"bearerAuth":[]}]},"post":{"description":"Maps an incoming telemetry port (e.g. `fuel_level`, `analog1`, `ble_temp_1`, `di1`) to a human-readable sensor with calibration curve.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Sensor mapped successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","port","sensor_type"],"properties":{"name":{"type":"string","example":"Reefer Cargo Temp Probe"},"port":{"type":"string","example":"ble_temp_1"},"sensor_type":{"type":"string","enum":["fuel","temperature","door","voltage","custom"],"example":"temperature"},"unit":{"type":"string","example":"°C"},"formula":{"type":"string","example":"raw * 0.1"}}},"example":{"name":"Reefer Cargo Temp Probe","port":"ble_temp_1","sensor_type":"temperature","unit":"°C"}}}},"tags":["Sensors"],"summary":"Attach or Map Sensor to Device Hardware Port","security":[{"bearerAuth":[]}]},"delete":{"description":"Clears all configured sensor port mappings and calibration curves for a device back to factory defaults.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"All sensors reset."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Reset All Sensors for Device","security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/sensors/{id}/fleet-scan":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Sensors Id Fleet-scan within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"port","in":"query","schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Sensors Id Fleet-scan"}},"/api/devices/{imei}/sensors/{id}/bulk-assign":{"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Sensors Id Bulk-assign in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"port":{"example":"any"},"device_ids":{"example":"any"},"override":{"example":"any"},"label":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Create or Trigger Devices Imei Sensors Id Bulk-assign"}},"/api/devices/{imei}/sensors/{id}":{"put":{"description":"Updates and overwrites properties of the target Devices Imei Sensors Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"unit":{"example":"any"},"formula_a":{"example":"any"},"formula_b":{"example":"any"},"min_value":{"example":"any"},"max_value":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Update Devices Imei Sensors Id"},"delete":{"description":"Permanently removes or unlinks the target Devices Imei Sensors Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Devices Imei Sensors Id"}},"/api/devices/{imei}/sensors/setup-summary":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Sensors Setup-summary within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Sensors Setup-summary"}},"/api/devices/{imei}/sensors/live":{"get":{"description":"Returns the latest calibrated sensor values evaluated through active math formulas and calibration tables.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Current calibrated sensor values.","content":{"application/json":{"example":{"success":true,"data":{"fuel_level":{"value":48.5,"unit":"L","formatted":"48.5 L"},"temperature":{"value":-18.2,"unit":"°C","formatted":"-18.2 °C"},"door":{"value":false,"formatted":"Closed"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Real-Time Live Calibrated Sensor Readings","security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/sensors/detected-ports":{"get":{"description":"Inspects raw incoming binary telemetry packets for this device to identify hardware ports (analog inputs, CAN-bus PIDs, BLE sensor beacons) that are transmitting data but not yet assigned to a display sensor.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of detected telemetry attributes available for mapping.","content":{"application/json":{"example":{"success":true,"data":[{"port":"analog1","latest_raw":3412,"inferred_type":"fuel"},{"port":"ble_temp_1","latest_raw":215,"inferred_type":"temperature"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Discover Unmapped Hardware Telemetry Ports","security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/sensors/visibility":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Sensors Visibility.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ports":{"example":"any"},"active":{"example":"any"},"mode":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Modify Devices Imei Sensors Visibility"}},"/api/devices/{imei}/sensors/{port}":{"put":{"description":"Updates polynomial formula, linear interpolation points, or display labels for an assigned sensor port.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Port identifier (e.g. fuel_level, analog1, temp1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Sensor configuration updated."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"example":"any"},"template_id":{"example":"any"},"formula_a":{"example":"any"},"formula_b":{"example":"any"},"calibration_table":{"example":"any"},"active":{"example":"any"},"favorite":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Update Sensor Calibration Table & Port Settings","security":[{"bearerAuth":[]}]},"delete":{"description":"Removes a sensor port assignment from a device.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Port identifier"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Sensor port removed."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Unmap Sensor Port","security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/sensors/{port}/readings":{"get":{"description":"Retrieves historical sensor time-series data (e.g. fuel drain slope, temperature logs) over a date range for graphing and analysis.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Port identifier"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"hours","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","description":"Start timestamp (ISO-8601 UTC)","schema":{"type":"string","example":"2026-10-01T00:00:00Z"}},{"name":"to","in":"query","description":"End timestamp (ISO-8601 UTC)","schema":{"type":"string","example":"2026-10-01T23:59:59Z"}}],"responses":{"200":{"description":"Time-series sensor readings."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Query Historical Sensor Readings Time-Series","security":[{"bearerAuth":[]}]},"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Sensors Port Readings in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"raw_value":{"example":"any"},"calibrated_value":{"example":"any"},"timestamp":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Create or Trigger Devices Imei Sensors Port Readings"}},"/api/devices/{imei}/sensors/{key}":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Sensors Key.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"battery_level"},"description":"Attribute or preference setting key"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"custom_label":{"example":"any"},"template_id":{"example":"any"},"hidden":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Modify Devices Imei Sensors Key"},"delete":{"description":"Permanently removes or unlinks the target Devices Imei Sensors Key from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"battery_level"},"description":"Attribute or preference setting key"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Devices Imei Sensors Key"}},"/api/devices/{imei}/detected-attributes":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Detected-attributes within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"showHidden","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Detected-attributes"},"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Detected-attributes in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"attribute_key":{"example":"any"},"raw_value":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Create or Trigger Devices Imei Detected-attributes"},"delete":{"description":"Permanently removes or unlinks the target Devices Imei Detected-attributes from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Devices Imei Detected-attributes"}},"/api/devices/{imei}/detected-attributes/{id}/fleet-scan":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Detected-attributes Id Fleet-scan within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"port","in":"query","schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Detected-attributes Id Fleet-scan"}},"/api/devices/{imei}/detected-attributes/{id}/bulk-assign":{"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Detected-attributes Id Bulk-assign in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"port":{"example":"any"},"device_ids":{"example":"any"},"override":{"example":"any"},"label":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Create or Trigger Devices Imei Detected-attributes Id Bulk-assign"}},"/api/devices/{imei}/detected-attributes/{id}":{"put":{"description":"Updates and overwrites properties of the target Devices Imei Detected-attributes Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"unit":{"example":"any"},"formula_a":{"example":"any"},"formula_b":{"example":"any"},"min_value":{"example":"any"},"max_value":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Update Devices Imei Detected-attributes Id"},"delete":{"description":"Permanently removes or unlinks the target Devices Imei Detected-attributes Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Devices Imei Detected-attributes Id"}},"/api/devices/{imei}/detected-attributes/setup-summary":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Detected-attributes Setup-summary within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Detected-attributes Setup-summary"}},"/api/devices/{imei}/detected-attributes/live":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Detected-attributes Live within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Detected-attributes Live"}},"/api/devices/{imei}/detected-attributes/detected-ports":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Detected-attributes Detected-ports within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Detected-attributes Detected-ports"}},"/api/devices/{imei}/detected-attributes/visibility":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Detected-attributes Visibility.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ports":{"example":"any"},"active":{"example":"any"},"mode":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Modify Devices Imei Detected-attributes Visibility"}},"/api/devices/{imei}/detected-attributes/{port}":{"put":{"description":"Updates and overwrites properties of the target Devices Imei Detected-attributes Port.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"example":"any"},"template_id":{"example":"any"},"formula_a":{"example":"any"},"formula_b":{"example":"any"},"calibration_table":{"example":"any"},"active":{"example":"any"},"favorite":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Update Devices Imei Detected-attributes Port"},"delete":{"description":"Permanently removes or unlinks the target Devices Imei Detected-attributes Port from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Devices Imei Detected-attributes Port"}},"/api/devices/{imei}/detected-attributes/{port}/readings":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Detected-attributes Port Readings within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"hours","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Devices Imei Detected-attributes Port Readings"},"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Detected-attributes Port Readings in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"raw_value":{"example":"any"},"calibrated_value":{"example":"any"},"timestamp":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Create or Trigger Devices Imei Detected-attributes Port Readings"}},"/api/devices/{imei}/detected-attributes/{key}":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Detected-attributes Key.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"battery_level"},"description":"Attribute or preference setting key"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"custom_label":{"example":"any"},"template_id":{"example":"any"},"hidden":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Modify Devices Imei Detected-attributes Key"},"delete":{"description":"Permanently removes or unlinks the target Devices Imei Detected-attributes Key from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"battery_level"},"description":"Attribute or preference setting key"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Devices Imei Detected-attributes Key"}},"/api/devices/{imei}/driver/scorecard":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Driver Scorecard within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"period","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}},{"name":"range","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Devices Imei Driver Scorecard"}},"/api/devices/{imei}/driver/scorecard/summary":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Driver Scorecard Summary within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"range","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Devices Imei Driver Scorecard Summary"}},"/api/devices/{imei}/driver/{id}/scores":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Driver Id Scores within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"range","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Devices Imei Driver Id Scores"}},"/api/devices/{imei}/driver/{id}/events":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Driver Id Events within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Devices Imei Driver Id Events"}},"/api/devices/{imei}/driver":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Driver within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Devices Imei Driver"},"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Driver in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"driver_id":{"example":"any"}}}}}},"tags":["Drivers"],"summary":"Create or Trigger Devices Imei Driver"}},"/api/devices/{imei}/driver/{id}":{"put":{"description":"Updates and overwrites properties of the target Devices Imei Driver Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"email":{"example":"any"},"phone":{"example":"any"}}}}}},"tags":["Drivers"],"summary":"Update Devices Imei Driver Id"},"delete":{"description":"Permanently removes or unlinks the target Devices Imei Driver Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Delete Devices Imei Driver Id"}},"/api/devices/{imei}/maintenance/upcoming":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Maintenance Upcoming within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Devices Imei Maintenance Upcoming"}},"/api/devices/{imei}/maintenance/alerts":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Maintenance Alerts within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"device_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Devices Imei Maintenance Alerts"}},"/api/devices/{imei}/maintenance/alerts/{id}/dismiss":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Maintenance Alerts Id Dismiss.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Modify Devices Imei Maintenance Alerts Id Dismiss"}},"/api/devices/{imei}/maintenance/digest":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Maintenance Digest within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Devices Imei Maintenance Digest"},"put":{"description":"Updates and overwrites properties of the target Devices Imei Maintenance Digest.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"frequency":{"example":"any"},"send_hour":{"example":"any"},"include_maintenance":{"example":"any"},"include_geofence":{"example":"any"},"include_speed":{"example":"any"},"include_sos":{"example":"any"},"email_override":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Update Devices Imei Maintenance Digest"}},"/api/devices/{imei}/maintenance/logs":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Maintenance Logs within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Devices Imei Maintenance Logs"},"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Maintenance Logs in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_id":{"example":"any"},"imei":{"example":"any"},"schedule_id":{"example":"any"},"type":{"example":"any"},"service_name":{"example":"any"},"service_date":{"example":"any"},"odometer":{"example":"any"},"odometer_km":{"example":"any"},"engine_hours":{"example":"any"},"cost":{"example":"any"},"notes":{"example":"any"},"performed_by":{"example":"any"},"workshop_name":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Create or Trigger Devices Imei Maintenance Logs"}},"/api/devices/{imei}/maintenance/schedules":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Devices Imei Maintenance Schedules within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Devices Imei Maintenance Schedules"},"post":{"description":"Provisions, dispatches, or creates a new Devices Imei Maintenance Schedules in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"interval_value":{"example":"any"},"notify_km_before":{"example":"any"},"notify_days_before":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Create or Trigger Devices Imei Maintenance Schedules"}},"/api/devices/{imei}/maintenance/schedules/{id}/deactivate":{"patch":{"description":"Applies partial field modifications to the target Devices Imei Maintenance Schedules Id Deactivate.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Modify Devices Imei Maintenance Schedules Id Deactivate"}},"/api/positions/{imei}":{"get":{"description":"Retrieves historical breadcrumb tracking coordinates, heading, speed, altitude, and sensor state for a device over a specific time range.\n \n### Spatial Downsampling & Filtering\n- **Outlier Filtering**: Automatically suppresses stationary GPS drift jitter (< 3 km/h anchor) and invalid speed spikes (> 150 km/h).\n- **LTTB (Largest Triangle Three Buckets)**: When querying long durations (e.g. 24h or 7 days), the API intelligently downsamples high-frequency points while preserving exact geometric road curves and turning points.\n- Query with `downsample=raw` or `downsample=0` to fetch 100% uncompressed raw points.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"example":100},"required":false,"description":"Maximum points to return when querying recent positions without date range (default: 100)"},{"name":"downsample","in":"query","schema":{"type":"string","example":"auto"},"required":false,"description":"Downsampling mode: \"auto\" (default, capped at 5000 pts), \"raw\" or \"0\" (full density), or target point count (e.g. 500)"},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"required":false,"description":"Start timestamp (ISO-8601 UTC)"},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"required":false,"description":"End timestamp (ISO-8601 UTC)"}],"responses":{"200":{"description":"Array of timestamped GPS position points.","content":{"application/json":{"example":{"success":true,"data":[{"time":"2026-10-01T10:14:00Z","imei":"864540081293581","lat":23.8103,"lon":90.4125,"speed":48,"course":180,"altitude":12,"satellites":14,"gps_valid":true,"raw_data":{"ignition":true,"external_voltage":13.8}}],"meta":{"total_positions":1420,"downsampled_to":1420,"algorithm":"raw_full_fidelity"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Position history locked — subscription expired."},"404":{"description":"Device not found."},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Positions"],"summary":"Get GPS Position History with LTTB Spatial Downsampling","security":[{"bearerAuth":[]}]}},"/api/positions/{imei}/latest":{"get":{"description":"Retrieves the single most recent telemetry packet for a vehicle. Uses an in-memory Redis cache (`device:last_pos:{imei}`) for sub-millisecond response latency, with automatic fallback to indexed storage.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Latest vehicle telemetry position and sensor snapshot.","content":{"application/json":{"example":{"success":true,"data":{"imei":"864540081293581","lat":23.8103,"lon":90.4125,"speed":52,"course":175,"ignition":true,"time":"2026-10-01T10:20:15Z","server_time":"2026-10-01T10:20:16Z","address":"Airport Road, Kurmitola, Dhaka","battery_voltage":13.8,"fuel_level":48.5}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Device or positions not found."},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Positions"],"summary":"Get Real-Time Latest Known Position (Sub-Millisecond Redis)","security":[{"bearerAuth":[]}]}},"/api/positions/{imei}/stops":{"get":{"description":"Computes stationary periods and parking stops where the vehicle was stationary with or without engine idling, including start time, end time, duration, and reverse geocoded address.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"},{"name":"min_minutes","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Array of detected vehicle stop events.","content":{"application/json":{"example":{"success":true,"data":[{"lat":23.7808,"lon":90.4152,"address":"Gulshan 2 Circle, Dhaka","start_time":"2026-10-01T08:15:00Z","end_time":"2026-10-01T09:00:00Z","duration_seconds":2700}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Positions"],"summary":"Get Vehicle Parking & Stop Duration Intervals","security":[{"bearerAuth":[]}]}},"/api/fleets/tree":{"get":{"description":"Returns nested parent-child fleet hierarchy with recursive path indexing, depth level, and aggregate device counts for building tree navigation menus and organizational charts.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"all"},"description":"Scope level: \"my\" (default), \"child\", or \"all\""}],"responses":{"200":{"description":"Hierarchical tree of fleet nodes.","content":{"application/json":{"example":{"success":true,"data":[{"id":14,"name":"Executive Fleet","depth":0,"device_count":12,"child_count":2,"path":"14","sort_path":"Executive Fleet"},{"id":22,"name":"Dhaka Division","depth":1,"parent_id":14,"device_count":6,"child_count":0,"path":"14.22","sort_path":"Executive Fleet/Dhaka Division"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fleets"],"summary":"Get Hierarchical Fleet Tree Structure","security":[{"bearerAuth":[]}]}},"/api/fleets":{"get":{"description":"Retrieves all fleet groups accessible to the current tenant user, annotated with active device counts. Supports filtering by organization scope (`scope=child` or `scope=all`).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Scope level: \"my\" (default), \"child\" (include sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of fleet groups.","content":{"application/json":{"example":{"success":true,"data":[{"id":14,"org_id":"90e544ce-d284-48f0-b8d4-63fcb001a1c5","name":"Executive Fleet","parent_id":null,"color":"#3b82f6","device_count":12,"org_name":"Xeekar Corp"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fleets"],"summary":"List All Fleets (Flat Array with Vehicle Counts)","security":[{"bearerAuth":[]}]},"post":{"description":"Creates a new logical vehicle group or sub-fleet under the organization hierarchy.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Fleet created successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Delivery Vans North"},"parent_id":{"type":"integer","description":"Parent fleet ID for nested grouping","example":14},"color":{"type":"string","description":"Hex color badge code","example":"#10b981"}}},"example":{"name":"Delivery Vans North","parent_id":14,"color":"#10b981"}}}},"tags":["Fleets"],"summary":"Create New Fleet Group","security":[{"bearerAuth":[]}]}},"/api/fleets/{id}":{"put":{"description":"Modifies the display name, nesting parent group, or accent badge color of a fleet.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","example":14},"description":"Fleet numeric ID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Fleet updated successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"VIP Executive Fleet"},"parent_id":{"type":"integer","example":null},"color":{"type":"string","example":"#6366f1"}}},"example":{"name":"VIP Executive Fleet","color":"#6366f1"}}}},"tags":["Fleets"],"summary":"Update Fleet Name, Parent & Color","security":[{"bearerAuth":[]}]},"delete":{"description":"Deletes a fleet group. Sub-fleets must be deleted first. Any devices assigned to this fleet have their `fleet_id` reset to NULL.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","example":14},"description":"Fleet numeric ID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Fleet deleted successfully."},"400":{"description":"Cannot delete fleet containing active sub-fleets."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fleets"],"summary":"Delete Fleet Group","security":[{"bearerAuth":[]}]}},"/api/groups/tree":{"get":{"description":"Retrieves a paginated list of Groups Tree accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fleets"],"summary":"Get Groups Tree"}},"/api/groups":{"get":{"description":"Retrieves a paginated list of Groups accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fleets"],"summary":"Get Groups"},"post":{"description":"Provisions, dispatches, or creates a new Groups in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"parent_id":{"example":"any"},"color":{"example":"any"}}}}}},"tags":["Fleets"],"summary":"Create or Trigger Groups"}},"/api/groups/{id}":{"put":{"description":"Updates and overwrites properties of the target Groups Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"parent_id":{"example":"any"},"color":{"example":"any"}}}}}},"tags":["Fleets"],"summary":"Update Groups Id"},"delete":{"description":"Permanently removes or unlinks the target Groups Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fleets"],"summary":"Delete Groups Id"}},"/api/geofences/categories":{"get":{"description":"Retrieves a paginated list of Geofences Categories accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Geofences"],"summary":"Get Geofences Categories"}},"/api/geofences":{"get":{"description":"Retrieves virtual perimeter boundaries configured for the organization, including center coordinates, radius, polygon GeoJSON coordinates, and category badges.\n\n### Multi-Tenant User Scoping\n- **Tenant Admins**: Can view all organization geofences across all users and fleets.\n- **Retail Users / Viewers**: Strictly scoped to private geofences they created (`created_by = userId`) plus public geofences (`category = 'public'`). Admin or other sub-user zones are isolated to prevent cross-account clutter.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"exclude_category","in":"query","schema":{"type":"string"}},{"name":"imei","in":"query","schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"category_id","in":"query","description":"Filter by geofence category ID","schema":{"type":"string","example":"depot"}}],"responses":{"200":{"description":"List of configured geofence shapes.","content":{"application/json":{"example":{"success":true,"data":[{"id":"4b5b9c44-979d-4c34-a877-564ea67fe7b4","name":"Central Logistics Yard","type":"circle","category":"general","color":"#3b82f6","created_by":"b6eb3d44-48d9-435f-bd59-2e51e0a27007","coordinates":{"center":[23.8103,90.4125],"radius":500},"speed_limit":20}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Geofences"],"summary":"List Organization Geofences (Circles & Polygons)","security":[{"bearerAuth":[]}]},"post":{"description":"Draws and saves a virtual geographic perimeter for monitoring vehicle entry, exit, dwell time, and localized speed limits. Automatically tags `created_by` to the authenticated user ID.\n \n### Geometry Formats\n- **Circle**: Requires `coordinates: { center: [lat, lon], radius: number }` or separate top-level `center_lat`, `center_lng`, and `radius` parameters.\n- **Polygon**: Requires `coordinates: [[lat, lon], [lat, lon], ...]` forming a closed boundary (minimum 3 coordinates).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Geofence created successfully with created_by user attribution."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string","example":"Central Logistics Yard"},"type":{"type":"string","enum":["circle","polygon"],"example":"circle"},"color":{"type":"string","default":"#FF0000","example":"#3b82f6"},"category":{"type":"string","default":"general","example":"depot"},"coordinates":{"type":"object","description":"Coordinates object (circle: { center: [lat, lng], radius: number }; polygon: [[lat, lng], ...])","example":{"center":[23.8103,90.4125],"radius":500}},"center_lat":{"type":"number","example":23.8103},"center_lng":{"type":"number","example":90.4125},"radius":{"type":"number","example":500},"speed_limit":{"type":"number","description":"Yard speed limit in km/h","example":20}}},"example":{"name":"Central Logistics Yard","type":"circle","coordinates":{"center":[23.8103,90.4125],"radius":500},"category":"general","color":"#3b82f6"}}}},"tags":["Geofences"],"summary":"Create Circular or Polygonal Geofence","security":[{"bearerAuth":[]}]}},"/api/geofences/import":{"post":{"description":"Uploads and parses a standard Google Earth KML file or GeoJSON feature collection to batch-create multiple geofences and highway transit corridors in one step.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Batch import summary with imported count.","content":{"application/json":{"example":{"success":true,"data":{"importedCount":12,"errors":[]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Geofences"],"summary":"Batch Import Geofences from KML or GeoJSON File","security":[{"bearerAuth":[]}]}},"/api/geofences/{id}":{"put":{"description":"Updates coordinates, radius, or metadata of an existing geofence.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"gf-central-depot"},"description":"Geofence UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Geofence updated."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"coordinates":{"example":"any"},"color":{"example":"any"},"category":{"example":"any"},"center_lat":{"example":"any"},"center_lng":{"example":"any"},"radius":{"example":"any"},"polygon":{"example":"any"}}}}}},"tags":["Geofences"],"summary":"Update Geofence Geometry, Name & Parameters","security":[{"bearerAuth":[]}]},"delete":{"description":"Permanently deletes a geofence and decouples it from any attached alert rules.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"gf-central-depot"},"description":"Geofence UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Geofence deleted."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Geofences"],"summary":"Delete Geofence","security":[{"bearerAuth":[]}]}},"/api/alerts":{"get":{"description":"Retrieves security and telematics alert events triggered across the fleet (overspeed, geofence enter/exit, harsh braking, panic SOS, ignition tampering).\n \n### Filtering\n- Filter by `status=active` or `status=acknowledged`.\n- Filter by severity: `critical`, `warning`, `info`.\n- Filter by specific vehicle IMEI or date range.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"integer","default":1,"example":1},"description":"Pagination page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"example":25},"description":"Number of alert records per page"},{"name":"type","in":"query","schema":{"type":"string","example":"overspeed"},"description":"Alert rule trigger type (e.g. overspeed, geofence_exit, sos, harsh_brake)"},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"},{"name":"search","in":"query","schema":{"type":"string","example":"Toyota"},"description":"Search filter keyword"},{"name":"sort","in":"query","schema":{"type":"string"}},{"name":"include_children","in":"query","schema":{"type":"string"}},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"has_video","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by acknowledgment status","schema":{"type":"string","example":"active","enum":["active","acknowledged","all"]}},{"name":"severity","in":"query","description":"Filter by alert severity","schema":{"type":"string","enum":["critical","warning","info"],"example":"critical"}},{"name":"imei","in":"query","description":"Filter to a specific vehicle IMEI","schema":{"type":"string","example":"864540081293581"}}],"responses":{"200":{"description":"Paginated list of alert event records.","content":{"application/json":{"example":{"success":true,"data":[{"id":"8a9c2d1e-45fa-43bc-91e8-71e89dfb6102","type":"overspeed","severity":"critical","title":"Speed Violation: 94 km/h","description":"Vehicle exceeded 80 km/h threshold on Airport Highway","device_id":"864540081293581","vehicle_name":"Toyota Allion 2024","status":"active","lat":23.8103,"lon":90.4125,"created_at":"2026-10-01T10:14:20Z"}],"pagination":{"page":1,"limit":25,"total":14,"totalPages":1}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"List Fleet Alert History with Filtering & Pagination","security":[{"bearerAuth":[]}]},"post":{"description":"Dispatches an instant high-priority SOS emergency alert from mobile app or in-cab panic button, alerting dispatchers and pushing priority push/SMS notifications.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"SOS alert broadcasted successfully."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imei"],"properties":{"imei":{"type":"string","example":"864540081293581"},"latitude":{"type":"number","example":23.8103},"longitude":{"type":"number","example":90.4125},"message":{"type":"string","example":"Emergency driver assistance requested"}}},"example":{"imei":"864540081293581","latitude":23.8103,"longitude":90.4125,"message":"Emergency driver assistance requested"}}}},"tags":["Alerts"],"summary":"Trigger Driver Emergency SOS / Panic Alert","security":[{"bearerAuth":[]}]}},"/api/alerts/history":{"get":{"description":"Retrieves a paginated list of Alerts History accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"},{"name":"search","in":"query","schema":{"type":"string","example":"Toyota"},"description":"Search filter keyword"},{"name":"sort","in":"query","schema":{"type":"string"}},{"name":"include_children","in":"query","schema":{"type":"string"}},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"has_video","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"Get Alerts History"}},"/api/alerts/sos":{"post":{"description":"Provisions, dispatches, or creates a new Alerts Sos in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"example":"any"},"latitude":{"example":"any"},"longitude":{"example":"any"},"lat":{"example":"any"},"lng":{"example":"any"},"lon":{"example":"any"},"device_imei":{"example":"any"},"deviceId":{"example":"any"},"timestamp":{"example":"any"},"message":{"example":"any"}}}}}},"tags":["Alerts"],"summary":"Create or Trigger Alerts Sos"}},"/api/alerts/acknowledge-all":{"put":{"description":"Updates and overwrites properties of the target Alerts Acknowledge-all.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"example":"any"},"type":{"example":"any"}}}}}},"tags":["Alerts"],"summary":"Update Alerts Acknowledge-all"},"post":{"description":"Clears or acknowledges all currently active alert notices for the organization in a single operation.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"All active alerts acknowledged."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"example":"any"},"type":{"example":"any"}}}}}},"tags":["Alerts"],"summary":"Bulk Acknowledge All Active Alerts","security":[{"bearerAuth":[]}]}},"/api/alerts/{id}/acknowledge":{"put":{"description":"Updates and overwrites properties of the target Alerts Id Acknowledge.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"Update Alerts Id Acknowledge"},"post":{"description":"Marks an individual alert as investigated and acknowledged by an operator, recording timestamp and user ID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"8a9c2d1e-45fa-43bc-91e8-71e89dfb6102"},"description":"Alert UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Alert marked as acknowledged."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"Acknowledge Specific Alert Event","security":[{"bearerAuth":[]}]}},"/api/alerts/{id}/ack":{"post":{"description":"Provisions, dispatches, or creates a new Alerts Id Ack in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"Create or Trigger Alerts Id Ack"}},"/api/alerts/rules":{"get":{"description":"Retrieves all automated notification and event detection rules created for the organization.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"includeTemplates","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of alert rules with trigger criteria and notification channels.","content":{"application/json":{"example":{"success":true,"data":[{"id":"rule-overspeed-80","name":"Highway Overspeed Alert","type":"overspeed","severity":"critical","enabled":true,"conditions":{"speed_limit":80,"duration_seconds":15},"channels":["push","email","sms"],"device_ids":["864540081293581"]}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"List Configured Alert Rules","security":[{"bearerAuth":[]}]},"post":{"description":"Configures a new telematics trigger condition that monitors live vehicle feeds and dispatches alerts upon violation.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Alert rule created successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string","example":"Highway Overspeed Alert"},"type":{"type":"string","enum":["overspeed","geofence_enter","geofence_exit","sos","power_cut","harsh_acceleration","harsh_braking","fuel_theft"],"example":"overspeed"},"severity":{"type":"string","enum":["critical","warning","info"],"default":"warning","example":"critical"},"config":{"type":"object","description":"Trigger threshold parameters (e.g. limit: 80, geofence_id, fuel_drop_liters). Can also be passed as \"conditions\".","example":{"limit":80}},"conditions":{"type":"object","description":"Alias for config parameter","example":{"speed_limit":80}},"notify_channels":{"type":"array","items":{"type":"string","enum":["push","email","sms","webhook"]},"example":["push","email"]},"channels":{"type":"array","items":{"type":"string","enum":["push","email","sms","webhook"]},"description":"Alias for notify_channels","example":["push","email"]},"device_ids":{"type":"array","items":{"type":"string"},"description":"List of assigned IMEIs, or omit for tenant-wide rule","example":["864540081293581"]},"cooldown_minutes":{"type":"number","default":10,"example":10}}},"example":{"name":"Highway Overspeed Alert","type":"overspeed","severity":"critical","config":{"limit":80},"notify_channels":["push","email"]}}}},"tags":["Alerts"],"summary":"Create Automated Alert Rule","security":[{"bearerAuth":[]}]}},"/api/alerts/rules/{id}":{"put":{"description":"Edits thresholds, assigned vehicle targets, or active notification channels for an alert rule.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"rule-overspeed-80"},"description":"Alert rule UUID or identifier"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Alert rule updated."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"config":{"example":"any"},"active":{"example":"any"},"device_ids":{"example":"any"},"fleet_ids":{"example":"any"},"cooldown_minutes":{"example":"any"},"schedule":{"example":"any"},"is_template":{"example":"any"},"template_name":{"example":"any"},"notify_channels":{"example":"any"}}}}}},"tags":["Alerts"],"summary":"Update Alert Rule Criteria & Channels","security":[{"bearerAuth":[]}]},"delete":{"description":"Permanently deactivates and removes an alert monitoring rule.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"rule-overspeed-80"},"description":"Alert rule identifier"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Alert rule deleted."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"Delete Alert Rule","security":[{"bearerAuth":[]}]}},"/api/alerts/templates":{"get":{"description":"Retrieves a paginated list of Alerts Templates accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"Get Alerts Templates"}},"/api/alerts/templates/apply":{"post":{"description":"Provisions, dispatches, or creates a new Alerts Templates Apply in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notifyChannels":{"example":"any"},"templateId":{"example":"any"},"deviceIds":{"example":"any"},"fleetIds":{"example":"any"},"notify_channels":{"example":"any"}}}}}},"tags":["Alerts"],"summary":"Create or Trigger Alerts Templates Apply"}},"/api/alerts/test-push":{"post":{"description":"Provisions, dispatches, or creates a new Alerts Test-push in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Alerts"],"summary":"Create or Trigger Alerts Test-push"}},"/api/commands/types":{"get":{"description":"Discovers all remote actuator commands supported by the platform and the target tracker hardware protocol (GT06, Jimi, Teltonika, Coban, JT808).\n \n### Command Capabilities\n- Returns standard parameters, dangerous level (e.g. engine cutoff), and channel support (GPRS TCP/UDP vs SMS).\n- Query with `?protocol=gt06` or `?protocol=teltonika` to narrow down to hardware-specific commands.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"protocol","in":"query","schema":{"type":"string","example":"gt06"},"description":"Hardware protocol identifier (e.g. gt06, teltonika, jt808, coban, meitrack, pilot)"}],"responses":{"200":{"description":"Array of supported command definitions with schemas and descriptions.","content":{"application/json":{"example":{"success":true,"data":[{"value":"relay_off","label":"Cut Off Engine (Relay Off)","description":"Activates external immobilizer relay to cut fuel pump / ignition","category":"security","dangerous":true},{"value":"relay_on","label":"Restore Engine (Relay On)","description":"Restores engine ignition relay to normal operational state","category":"security","dangerous":false},{"value":"reboot","label":"Restart Tracker Hardware","description":"Sends hardware reboot instruction to GSM/GPS module","category":"maintenance","dangerous":false},{"value":"custom","label":"Raw Protocol String / Custom AT Command","description":"Direct hex/string payload sent over active GPRS socket","category":"advanced","dangerous":true}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Commands"],"summary":"List Supported Hardware Command Types & Protocols","security":[{"bearerAuth":[]}]}},"/api/commands/templates":{"get":{"description":"Retrieves predefined reusable command presets configured for the tenant organization (e.g., standard ping intervals, immobilizer triggers, buzzer alerts).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of configured command templates.","content":{"application/json":{"example":{"success":true,"data":[{"id":3,"name":"Emergency Immobilize (Safe Stop)","protocol":"gt06","command_type":"relay_off","payload":"RELAY,1#","channel":"gprs","description":"Safely locks the vehicle engine upon next zero-speed event","created_at":"2026-09-15T08:30:00Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Commands"],"summary":"List Saved Organization Command Templates","security":[{"bearerAuth":[]}]},"post":{"description":"Saves a reusable command recipe for rapid dispatch across single or multiple devices in the fleet.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Template created successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","commandType"],"properties":{"name":{"type":"string","example":"Set Reporting 10s"},"protocol":{"type":"string","example":"gt06"},"commandType":{"type":"string","example":"custom"},"payload":{"type":"string","example":"TIMER,10,10#"},"parameters":{"type":"object","example":{"interval":10}},"description":{"type":"string","example":"Sets 10s moving interval"},"channel":{"type":"string","enum":["gprs","sms"],"example":"gprs"}}},"example":{"name":"Set Reporting 10s","protocol":"gt06","commandType":"custom","payload":"TIMER,10,10#","description":"Sets 10s moving interval","channel":"gprs"}}}},"tags":["Commands"],"summary":"Create Command Template","security":[{"bearerAuth":[]}]}},"/api/commands/templates/{id}":{"delete":{"description":"Removes an existing command preset from the organization catalog.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"3"},"description":"Command template UUID or numeric identifier"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Template deleted."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Template not found."},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Commands"],"summary":"Delete Command Template","security":[{"bearerAuth":[]}]}},"/api/commands/{imei}":{"get":{"description":"Retrieves the execution history of all remote commands dispatched to a specific tracker, including queue status (`queued`, `sent`, `executed`, `failed`), timestamps, and device replies.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device hardware IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of sent commands and their execution acknowledgments.","content":{"application/json":{"example":{"success":true,"data":[{"id":1084,"device_id":"864540081293581","command_type":"relay_off","command":"RELAY,1#","status":"executed","channel":"gprs","response":"Cut off the fuel supply success","sent_by_name":"Super Admin","created_at":"2026-10-01T10:14:02Z","delivered_at":"2026-10-01T10:14:03Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Commands"],"summary":"Get Command Audit Log & Delivery Status for Device","security":[{"bearerAuth":[]}]},"post":{"description":"Dispatches an instant control command to a live tracker over active TCP/UDP socket, or via Outbound SMS gateway if device is offline.\n \n### Safety & Permissions\n- **Engine Cutoff / Immobilization**: Requires explicit `commands:engine_cut` RBAC permission.\n- **Subscription Lock**: Devices with expired subscriptions cannot receive actuator commands.\n- Commands are pushed via Redis pub/sub directly to the connected telematics protocol gateway.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit target device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Command successfully queued or sent to the device.","content":{"application/json":{"example":{"success":true,"data":{"id":1085,"device_id":"864540081293581","command_type":"relay_off","status":"queued","channel":"gprs"}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Access denied: Subscription expired or user lacks commands:engine_cut permission."},"404":{"description":"Device not found in tenant organization."},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"commandType":{"type":"string","description":"Command type: relay_off, relay_on, reboot, position, or custom","example":"relay_off"},"channel":{"type":"string","enum":["gprs","sms"],"default":"gprs","description":"Transmission channel (GPRS is fast real-time socket; SMS is cellular fallback)","example":"gprs"},"templateId":{"type":"string","description":"Optional ID of preconfigured template to inherit parameters from","example":"3"},"params":{"type":"object","description":"Additional parameters or payload data for custom commands","example":{"state":"0","data":"RELAY,1#"}}}},"example":{"commandType":"relay_off","channel":"gprs","params":{"reason":"Unauthorized route deviation"}}}}},"tags":["Commands"],"summary":"Send Remote Hardware Command (GPRS / SMS)","security":[{"bearerAuth":[]}]}},"/api/commands/batch-preset":{"post":{"description":"Dispatches standard bulk commands across a fleet of devices simultaneously (e.g. disabling LBS cellular triangulation, configuring 10-second high-precision tracking, or static filtering).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Batch command dispatch summary.","content":{"application/json":{"example":{"success":true,"data":{"sentCount":2,"failedCount":0,"results":[{"imei":"864540081293581","status":"queued","commandLogId":1086},{"imei":"865167047241865","status":"queued","commandLogId":1087}]}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["presetId","imeis"],"properties":{"presetId":{"type":"string","description":"Preset key: _disable_lbs, _set_moving_interval_10s, _set_static_filter, _set_angle_upload, or custom string","example":"_set_moving_interval_10s"},"imeis":{"type":"array","items":{"type":"string"},"description":"Array of target 15-digit device IMEIs","example":["864540081293581","865167047241865"]}}},"example":{"presetId":"_set_moving_interval_10s","imeis":["864540081293581","865167047241865"]}}}},"tags":["Commands"],"summary":"Send Batch Configuration Preset to Multiple Devices","security":[{"bearerAuth":[]}]}},"/api/sensor-templates":{"get":{"description":"Retrieves library of reusable sensor configurations (fuel capacitive probes, ultrasonic sensors, digital temperature probes, door switches, axle load sensors) with standard formulas and scaling coefficients.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"showHidden","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of sensor templates.","content":{"application/json":{"example":{"success":true,"data":[{"id":"tmpl-dut-e-fuel","name":"Technoton DUT-E RS485 Fuel Sensor","sensor_type":"fuel","unit":"L","formula":"raw * 0.1","calibration_points":[{"raw":0,"val":0},{"raw":1023,"val":60}]}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"List Master Sensor Templates Catalog","security":[{"bearerAuth":[]}]},"post":{"description":"Defines a new standardized sensor profile with calibration curves, math formulas, and unit conversion for reuse across devices.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Sensor template created successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","sensor_type"],"properties":{"name":{"type":"string","example":"Omnicomm LLS Fuel Sensor"},"sensor_type":{"type":"string","enum":["fuel","temperature","door","ignition","battery","axle_load","engine_rpm","custom"],"example":"fuel"},"unit":{"type":"string","example":"L"},"formula":{"type":"string","example":"raw * 0.1"}}},"example":{"name":"Omnicomm LLS Fuel Sensor","sensor_type":"fuel","unit":"L","formula":"raw * 0.1"}}}},"tags":["Sensors"],"summary":"Create New Master Sensor Template","security":[{"bearerAuth":[]}]},"delete":{"description":"Permanently removes or unlinks the target Sensor-templates from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Sensor-templates"}},"/api/sensor-templates/{id}/fleet-scan":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Sensor-templates Id Fleet-scan within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"port","in":"query","schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Sensor-templates Id Fleet-scan"}},"/api/sensor-templates/{id}/bulk-assign":{"post":{"description":"Provisions, dispatches, or creates a new Sensor-templates Id Bulk-assign in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"port":{"example":"any"},"device_ids":{"example":"any"},"override":{"example":"any"},"label":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Create or Trigger Sensor-templates Id Bulk-assign"}},"/api/sensor-templates/{id}":{"put":{"description":"Updates calibration parameters, conversion formula, or units for a master sensor template.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"tmpl-dut-e-fuel"},"description":"Sensor template ID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Sensor template updated."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"unit":{"example":"any"},"formula_a":{"example":"any"},"formula_b":{"example":"any"},"min_value":{"example":"any"},"max_value":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Update Sensor Template Specification","security":[{"bearerAuth":[]}]},"delete":{"description":"Removes a sensor template from the catalog.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"tmpl-dut-e-fuel"},"description":"Sensor template ID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Sensor template deleted."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Sensor Template","security":[{"bearerAuth":[]}]}},"/api/sensor-templates/setup-summary":{"get":{"description":"Retrieves a paginated list of Sensor-templates Setup-summary accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Sensor-templates Setup-summary"}},"/api/sensor-templates/live":{"get":{"description":"Retrieves a paginated list of Sensor-templates Live accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Sensor-templates Live"}},"/api/sensor-templates/detected-ports":{"get":{"description":"Retrieves a paginated list of Sensor-templates Detected-ports accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Sensor-templates Detected-ports"}},"/api/sensor-templates/visibility":{"patch":{"description":"Applies partial field modifications to the target Sensor-templates Visibility.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ports":{"example":"any"},"active":{"example":"any"},"mode":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Modify Sensor-templates Visibility"}},"/api/sensor-templates/{port}":{"put":{"description":"Updates and overwrites properties of the target Sensor-templates Port.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"example":"any"},"template_id":{"example":"any"},"formula_a":{"example":"any"},"formula_b":{"example":"any"},"calibration_table":{"example":"any"},"active":{"example":"any"},"favorite":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Update Sensor-templates Port"},"delete":{"description":"Permanently removes or unlinks the target Sensor-templates Port from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Sensor-templates Port"}},"/api/sensor-templates/{port}/readings":{"get":{"description":"Retrieves a paginated list of Sensor-templates Port Readings accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"hours","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Get Sensor-templates Port Readings"},"post":{"description":"Provisions, dispatches, or creates a new Sensor-templates Port Readings in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"port","in":"path","required":true,"schema":{"type":"string","example":"fuel_level"},"description":"Hardware telemetry port identifier (e.g. fuel_level, analog1, ble_temp_1)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"raw_value":{"example":"any"},"calibrated_value":{"example":"any"},"timestamp":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Create or Trigger Sensor-templates Port Readings"}},"/api/sensor-templates/{key}":{"patch":{"description":"Applies partial field modifications to the target Sensor-templates Key.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"battery_level"},"description":"Attribute or preference setting key"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"custom_label":{"example":"any"},"template_id":{"example":"any"},"hidden":{"example":"any"}}}}}},"tags":["Sensors"],"summary":"Modify Sensor-templates Key"},"delete":{"description":"Permanently removes or unlinks the target Sensor-templates Key from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"battery_level"},"description":"Attribute or preference setting key"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Sensors"],"summary":"Delete Sensor-templates Key"}},"/api/drivers/scorecard":{"get":{"description":"Calculates aggregate safety scores based on harsh acceleration, hard cornering, harsh braking, overspeed durations, and unnecessary idling.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"period","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}},{"name":"range","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Driver scorecards and penalty breakdown."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Safety & Eco-Driving Scorecard for All Drivers","security":[{"bearerAuth":[]}]}},"/api/drivers/scorecard/summary":{"get":{"description":"Retrieves a paginated list of Drivers Scorecard Summary accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"range","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Drivers Scorecard Summary"}},"/api/drivers/{id}/scores":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Drivers Id Scores within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"range","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Drivers Id Scores"}},"/api/drivers/{id}/events":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Drivers Id Events within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Get Drivers Id Events"}},"/api/drivers":{"get":{"description":"Retrieves all commercial drivers enrolled in the organization, including driving license number, expiration date, assigned vehicle, contact phone, and safety rating.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of drivers.","content":{"application/json":{"example":{"success":true,"data":[{"id":"drv-01","name":"Rahim Khan","license_number":"DL-84729104","license_expiry":"2028-05-12","phone":"+8801712345678","assigned_vehicle_imei":"864540081293581","safety_score":94}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"List Registered Fleet Drivers","security":[{"bearerAuth":[]}]},"post":{"description":"Registers a new driver into the fleet directory, with license details and emergency contacts.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"201":{"description":"Driver enrolled successfully."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Rahim Khan"},"email":{"type":"string","format":"email","description":"Driver login email (optional, auto-generated from phone if omitted)","example":"driver.rahim@xeekar.com"},"phone":{"type":"string","example":"+8801712345678"},"password":{"type":"string","minLength":4,"maxLength":10,"description":"Driver app login password","example":"Temp1234"},"license_number":{"type":"string","description":"Driving license number","example":"DL-84729104"},"license_expiry":{"type":"string","example":"2028-05-12"},"assigned_vehicle_imei":{"type":"string","example":"864540081293581"}}},"example":{"name":"Rahim Khan","phone":"+8801712345678","license_number":"DL-84729104","license_expiry":"2028-05-12","password":"Temp1234"}}}},"tags":["Drivers"],"summary":"Enroll New Driver Profile","security":[{"bearerAuth":[]}]}},"/api/drivers/{id}":{"put":{"description":"Modifies driver details, phone numbers, or license expiration renewal.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"drv-01"},"description":"Driver ID or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Driver profile updated."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"email":{"example":"any"},"phone":{"example":"any"}}}}}},"tags":["Drivers"],"summary":"Update Driver Profile & License Validity","security":[{"bearerAuth":[]}]},"delete":{"description":"Removes a driver from the system. Unassigns any currently linked vehicles.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"drv-01"},"description":"Driver ID or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Driver removed."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Drivers"],"summary":"Delete Driver Profile","security":[{"bearerAuth":[]}]}},"/api/maintenance/upcoming":{"get":{"description":"Lists vehicles due for periodic servicing (engine oil change, brake pad inspection, tire rotation) based on odometer mileage, engine run hours, or calendar intervals.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of vehicles with due or overdue maintenance services.","content":{"application/json":{"example":{"success":true,"data":[{"imei":"864540081293581","vehicle_name":"Toyota Allion 2024","service_name":"Engine Oil & Filter Change","interval_km":5000,"current_odometer_km":18450,"due_at_km":20000,"km_remaining":1550,"status":"upcoming"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Upcoming Vehicle Maintenance & Service Schedules","security":[{"bearerAuth":[]}]}},"/api/maintenance/alerts":{"get":{"description":"Retrieves a paginated list of Maintenance Alerts accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"device_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Maintenance Alerts"}},"/api/maintenance/alerts/{id}/dismiss":{"patch":{"description":"Applies partial field modifications to the target Maintenance Alerts Id Dismiss.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Modify Maintenance Alerts Id Dismiss"}},"/api/maintenance/digest":{"get":{"description":"Retrieves a paginated list of Maintenance Digest accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Maintenance Digest"},"put":{"description":"Updates and overwrites properties of the target Maintenance Digest.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"frequency":{"example":"any"},"send_hour":{"example":"any"},"include_maintenance":{"example":"any"},"include_geofence":{"example":"any"},"include_speed":{"example":"any"},"include_sos":{"example":"any"},"email_override":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Update Maintenance Digest"}},"/api/maintenance/logs":{"get":{"description":"Retrieves historical maintenance records, invoices, parts replaced, and costs recorded by fleet mechanics.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of completed maintenance logs."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"List Maintenance Service History Logs","security":[{"bearerAuth":[]}]},"post":{"description":"Records a completed service event, resetting the service interval counter and archiving parts and workshop invoice costs.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Maintenance record saved and interval reset."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cost"],"properties":{"device_id":{"type":"string","description":"Device IMEI (or pass as imei)","example":"864540081293581"},"imei":{"type":"string","description":"Alias for device_id","example":"864540081293581"},"service_name":{"type":"string","description":"Description of service performed (or pass as type)","example":"Mobil 1 5W-30 Oil Change"},"type":{"type":"string","description":"Service type code (alias for service_name)","example":"general_service"},"cost":{"type":"number","example":4500},"odometer_km":{"type":"number","description":"Odometer reading (or pass as odometer)","example":18450},"odometer":{"type":"number","description":"Alias for odometer_km","example":18450},"workshop_name":{"type":"string","description":"Workshop name (or pass as performed_by)","example":"Navana Toyota Service Center"},"performed_by":{"type":"string","description":"Alias for workshop_name","example":"Navana Toyota Service Center"},"notes":{"type":"string","example":"Oil filter replaced; brake pads checked at 70%"}}},"example":{"imei":"864540081293581","service_name":"Mobil 1 5W-30 Oil Change","cost":4500,"odometer_km":18450,"workshop_name":"Navana Toyota Service Center"}}}},"tags":["Maintenance"],"summary":"Log Completed Service / Maintenance Event","security":[{"bearerAuth":[]}]}},"/api/maintenance/schedules":{"get":{"description":"Retrieves a paginated list of Maintenance Schedules accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Maintenance Schedules"},"post":{"description":"Provisions, dispatches, or creates a new Maintenance Schedules in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"interval_value":{"example":"any"},"notify_km_before":{"example":"any"},"notify_days_before":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Create or Trigger Maintenance Schedules"}},"/api/maintenance/schedules/{id}/deactivate":{"patch":{"description":"Applies partial field modifications to the target Maintenance Schedules Id Deactivate.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Modify Maintenance Schedules Id Deactivate"}},"/api/service-intervals/upcoming":{"get":{"description":"Retrieves a paginated list of Service-intervals Upcoming accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Service-intervals Upcoming"}},"/api/service-intervals/alerts":{"get":{"description":"Retrieves a paginated list of Service-intervals Alerts accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"device_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Service-intervals Alerts"}},"/api/service-intervals/alerts/{id}/dismiss":{"patch":{"description":"Applies partial field modifications to the target Service-intervals Alerts Id Dismiss.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Modify Service-intervals Alerts Id Dismiss"}},"/api/service-intervals/digest":{"get":{"description":"Retrieves a paginated list of Service-intervals Digest accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Service-intervals Digest"},"put":{"description":"Updates and overwrites properties of the target Service-intervals Digest.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"frequency":{"example":"any"},"send_hour":{"example":"any"},"include_maintenance":{"example":"any"},"include_geofence":{"example":"any"},"include_speed":{"example":"any"},"include_sos":{"example":"any"},"email_override":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Update Service-intervals Digest"}},"/api/service-intervals/logs":{"get":{"description":"Retrieves a paginated list of Service-intervals Logs accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Service-intervals Logs"},"post":{"description":"Provisions, dispatches, or creates a new Service-intervals Logs in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_id":{"example":"any"},"imei":{"example":"any"},"schedule_id":{"example":"any"},"type":{"example":"any"},"service_name":{"example":"any"},"service_date":{"example":"any"},"odometer":{"example":"any"},"odometer_km":{"example":"any"},"engine_hours":{"example":"any"},"cost":{"example":"any"},"notes":{"example":"any"},"performed_by":{"example":"any"},"workshop_name":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Create or Trigger Service-intervals Logs"}},"/api/service-intervals/schedules":{"get":{"description":"Retrieves a paginated list of Service-intervals Schedules accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Get Service-intervals Schedules"},"post":{"description":"Provisions, dispatches, or creates a new Service-intervals Schedules in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"interval_value":{"example":"any"},"notify_km_before":{"example":"any"},"notify_days_before":{"example":"any"}}}}}},"tags":["Maintenance"],"summary":"Create or Trigger Service-intervals Schedules"}},"/api/service-intervals/schedules/{id}/deactivate":{"patch":{"description":"Applies partial field modifications to the target Service-intervals Schedules Id Deactivate.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Maintenance"],"summary":"Modify Service-intervals Schedules Id Deactivate"}},"/api/reports/types":{"get":{"description":"Discovers all available report generator templates in the platform (e.g. Trips Summary, Stop & Idle Durations, Daily Distance Traveled, Fuel Consumption & Thefts, Speed Violations, Driver Scorecard, Geofence In/Out).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Array of report templates with filter definitions and export formats (PDF, Excel, CSV)."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"List Supported Fleet Report Types","security":[{"bearerAuth":[]}]}},"/api/reports/scheduled":{"get":{"description":"Retrieves a paginated list of Reports Scheduled accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Get Reports Scheduled"},"post":{"description":"Provisions, dispatches, or creates a new Reports Scheduled in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"format":{"example":"any"},"device_ids":{"example":"any"},"data_items":{"example":"any"},"options":{"example":"any"},"frequency":{"example":"any"},"time_of_day":{"example":"any"},"day_of_week":{"example":"any"},"day_of_month":{"example":"any"},"timezone":{"example":"any"},"email_recipients":{"example":"any"}}}}}},"tags":["Reports"],"summary":"Create or Trigger Reports Scheduled"}},"/api/reports/scheduled/{id}":{"put":{"description":"Updates and overwrites properties of the target Reports Scheduled Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Update Reports Scheduled Id"},"delete":{"description":"Permanently removes or unlinks the target Reports Scheduled Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Delete Reports Scheduled Id"}},"/api/reports/scheduled/{id}/run-now":{"post":{"description":"Provisions, dispatches, or creates a new Reports Scheduled Id Run-now in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Create or Trigger Reports Scheduled Id Run-now"}},"/api/reports/trips":{"get":{"description":"Generates a detailed summary of all vehicle trips over a date range, with start/end timestamps, duration, distance (km), max speed, average speed, and idle time.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"snap_to_roads","in":"query","schema":{"type":"string"}},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"origin_geofence_id","in":"query","schema":{"type":"string"}},{"name":"destination_geofence_id","in":"query","schema":{"type":"string"}},{"name":"min_stop_minutes","in":"query","schema":{"type":"string"}},{"name":"imei","in":"query","description":"Target vehicle 15-digit IMEI (omit for entire fleet)","schema":{"type":"string","example":"864540081293581"}},{"name":"from","in":"query","required":true,"description":"Start date/time (ISO-8601 UTC)","schema":{"type":"string","example":"2026-10-01T00:00:00Z"}},{"name":"to","in":"query","required":true,"description":"End date/time (ISO-8601 UTC)","schema":{"type":"string","example":"2026-10-01T23:59:59Z"}}],"responses":{"200":{"description":"Trips summary report records."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Generate Trips & Distance Summary Report","security":[{"bearerAuth":[]}]}},"/api/reports/trip-route":{"get":{"description":"Retrieves a paginated list of Reports Trip-route accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"start_time","in":"query","schema":{"type":"string"}},{"name":"end_time","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Get Reports Trip-route"}},"/api/reports/generate":{"post":{"description":"Enqueues an asynchronous report generation task in the worker cluster. Supports heavy multi-month or whole-fleet queries and returns a job token to poll for PDF/Excel download readiness.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"202":{"description":"Report job accepted and processing in background."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","from","to"],"properties":{"type":{"type":"string","enum":["trips","stops","fuel","overspeed","geofence","mileage"],"example":"fuel"},"format":{"type":"string","enum":["pdf","xlsx","csv"],"default":"pdf","example":"pdf"},"from":{"type":"string","example":"2026-09-01T00:00:00Z"},"to":{"type":"string","example":"2026-09-30T23:59:59Z"},"device_ids":{"type":"array","items":{"type":"string"},"description":"Target vehicle device IMEIs","example":["864540081293581"]},"imeis":{"type":"array","items":{"type":"string"},"description":"Alias for device_ids","example":["864540081293581"]}}},"example":{"type":"fuel","format":"pdf","from":"2026-09-01T00:00:00Z","to":"2026-09-30T23:59:59Z"}}}},"tags":["Reports"],"summary":"Trigger Asynchronous Background Report Generation","security":[{"bearerAuth":[]}]}},"/api/reports/download/{filename}":{"get":{"description":"Downloads the compiled report document artifact using the filename generated by the background worker.","produces":[null],"parameters":[{"name":"filename","in":"path","required":true,"schema":{"type":"string","example":"fuel-report-20261001.pdf"},"description":"Report output filename (e.g. fuel-report-20261001.pdf)"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Report binary file stream.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Download Generated PDF, Excel or CSV Report File","security":[{"bearerAuth":[]}]}},"/api/reports/create":{"post":{"description":"Provisions, dispatches, or creates a new Reports Create in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"type":{"example":"any"},"format":{"example":"any"},"device_ids":{"example":"any"},"date_from":{"example":"any"},"date_to":{"example":"any"},"data_items":{"example":"any"},"options":{"example":"any"}}}}}},"tags":["Reports"],"summary":"Create or Trigger Reports Create"}},"/api/reports":{"get":{"description":"Retrieves a paginated list of Reports accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Get Reports"}},"/api/reports/settings":{"get":{"description":"Retrieves a paginated list of Reports Settings accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Get Reports Settings"},"put":{"description":"Updates and overwrites properties of the target Reports Settings.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"auto_delete_days":{"example":"any"},"auto_delete_enabled":{"example":"any"},"max_file_size_mb":{"example":"any"}}}}}},"tags":["Reports"],"summary":"Update Reports Settings"}},"/api/reports/settings/cleanup":{"post":{"description":"Provisions, dispatches, or creates a new Reports Settings Cleanup in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Create or Trigger Reports Settings Cleanup"}},"/api/reports/{id}/retry":{"post":{"description":"Provisions, dispatches, or creates a new Reports Id Retry in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Create or Trigger Reports Id Retry"}},"/api/reports/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Reports Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Get Reports Id"},"delete":{"description":"Permanently removes or unlinks the target Reports Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Reports"],"summary":"Delete Reports Id"}},"/api/tasks":{"get":{"description":"Retrieves a paginated list of Tasks accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"driver_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Tasks"],"summary":"Get Tasks"},"post":{"description":"Provisions, dispatches, or creates a new Tasks in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"example":"any"},"description":{"example":"any"},"device_id":{"example":"any"},"driver_id":{"example":"any"},"location_lat":{"example":"any"},"location_lon":{"example":"any"},"address":{"example":"any"},"due_at":{"example":"any"},"priority":{"example":"any"}}}}}},"tags":["Tasks"],"summary":"Create or Trigger Tasks"}},"/api/tasks/{id}":{"put":{"description":"Updates and overwrites properties of the target Tasks Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"example":"any"},"driver_id":{"example":"any"},"completed_at":{"example":"any"}}}}}},"tags":["Tasks"],"summary":"Update Tasks Id"},"delete":{"description":"Permanently removes or unlinks the target Tasks Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Tasks"],"summary":"Delete Tasks Id"}},"/api/tasks/{id}/status":{"patch":{"description":"Applies partial field modifications to the target Tasks Id Status.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"example":"any"},"origin_lat":{"example":"any"},"origin_lon":{"example":"any"}}}}}},"tags":["Tasks"],"summary":"Modify Tasks Id Status"}},"/api/tasks/{id}/eta":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Tasks Id Eta within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Tasks"],"summary":"Get Tasks Id Eta"}},"/api/routes":{"get":{"description":"Retrieves a paginated list of Routes accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Routes"],"summary":"Get Routes"},"post":{"description":"Provisions, dispatches, or creates a new Routes in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"waypoints":{"example":"any"},"color":{"example":"any"},"distance_km":{"example":"any"},"corridor_km":{"example":"any"}}}}}},"tags":["Routes"],"summary":"Create or Trigger Routes"}},"/api/routes/directions":{"post":{"description":"Provisions, dispatches, or creates a new Routes Directions in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"waypoints":{"example":"any"}}}}}},"tags":["Routes"],"summary":"Create or Trigger Routes Directions"}},"/api/routes/nearest":{"get":{"description":"Retrieves a paginated list of Routes Nearest accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"lat","in":"query","schema":{"type":"string"}},{"name":"lon","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Routes"],"summary":"Get Routes Nearest"}},"/api/routes/match":{"post":{"description":"Provisions, dispatches, or creates a new Routes Match in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"length":{"example":"any"},"req.body":{"example":"any"}}}}}},"tags":["Routes"],"summary":"Create or Trigger Routes Match"}},"/api/routes/{id}":{"put":{"description":"Updates and overwrites properties of the target Routes Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"waypoints":{"example":"any"},"color":{"example":"any"},"distance_km":{"example":"any"},"corridor_km":{"example":"any"}}}}}},"tags":["Routes"],"summary":"Update Routes Id"},"delete":{"description":"Permanently removes or unlinks the target Routes Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Routes"],"summary":"Delete Routes Id"}},"/api/pois":{"get":{"description":"Retrieves geographic points of interest (gas stations, customer delivery docks, resting areas, ports) with coordinate pins and contact numbers.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"category","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of POI markers."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["POI"],"summary":"List Points of Interest (POI) & Yard Waypoints","security":[{"bearerAuth":[]}]},"post":{"description":"Saves a new custom geographic landmark with category icon and radius.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"POI saved."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"category":{"example":"any"},"lat":{"example":"any"},"lon":{"example":"any"},"address":{"example":"any"},"icon":{"example":"any"},"color":{"example":"any"}}}}}},"tags":["POI"],"summary":"Create Point of Interest (POI)","security":[{"bearerAuth":[]}]}},"/api/pois/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Pois Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["POI"],"summary":"Get Pois Id"},"put":{"description":"Updates and overwrites properties of the target Pois Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"category":{"example":"any"},"lat":{"example":"any"},"lon":{"example":"any"},"address":{"example":"any"},"icon":{"example":"any"},"color":{"example":"any"}}}}}},"tags":["POI"],"summary":"Update Pois Id"},"delete":{"description":"Permanently removes or unlinks the target Pois Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["POI"],"summary":"Delete Pois Id"}},"/api/stats":{"get":{"description":"Retrieves a paginated list of Stats accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"range","in":"query","schema":{"type":"string"}},{"name":"deviceId","in":"query","schema":{"type":"string","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b"},"description":"Device UUID or hardware identifier"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Stats"],"summary":"Get Stats"}},"/api/stats/organizations":{"get":{"description":"Retrieves a paginated list of Stats Organizations accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Stats"],"summary":"Get Stats Organizations"}},"/api/organizations":{"get":{"description":"Retrieves a paginated list of Organizations accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"range","in":"query","schema":{"type":"string"}},{"name":"deviceId","in":"query","schema":{"type":"string","example":"c1f7b76e-347f-44de-9e5c-0c153b664d4b"},"description":"Device UUID or hardware identifier"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Organizations"}},"/api/organizations/organizations":{"get":{"description":"Retrieves a paginated list of Organizations Organizations accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Organizations"],"summary":"Get Organizations Organizations"}},"/api/admin/unknown-devices":{"get":{"description":"Displays unassigned GPS trackers that have established a TCP/UDP connection and are sending packets to the gateway, but whose IMEIs have not yet been approved or mapped to an organization.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"}],"responses":{"200":{"description":"List of unapproved devices transmitting telemetry.","content":{"application/json":{"example":{"success":true,"data":[{"imei":"869281048201948","protocol":"gt06","ip":"103.24.12.5","port":5023,"packets_received":42,"first_seen":"2026-10-01T09:12:00Z","last_seen":"2026-10-01T10:15:20Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Unknown Devices"],"summary":"List Unrecognized Hardware in Quarantine Pool","security":[{"bearerAuth":[]}]}},"/api/admin/unknown-devices/count":{"get":{"description":"Retrieves a paginated list of Admin Unknown-devices Count accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Unknown Devices"],"summary":"Get Admin Unknown-devices Count"}},"/api/admin/unknown-devices/bulk-approve":{"post":{"description":"Provisions, dispatches, or creates a new Admin Unknown-devices Bulk-approve in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"}}}}}},"tags":["Unknown Devices"],"summary":"Create or Trigger Admin Unknown-devices Bulk-approve"}},"/api/admin/unknown-devices/{imei}/approve":{"post":{"description":"Provisions, dispatches, or creates a new Admin Unknown-devices Imei Approve in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"example":"any"}}}}}},"tags":["Unknown Devices"],"summary":"Create or Trigger Admin Unknown-devices Imei Approve"}},"/api/admin/unknown-devices/{imei}/reject":{"post":{"description":"Provisions, dispatches, or creates a new Admin Unknown-devices Imei Reject in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"example":"any"}}}}}},"tags":["Unknown Devices"],"summary":"Create or Trigger Admin Unknown-devices Imei Reject"}},"/api/admin/unknown-devices/{imei}/ignore":{"post":{"description":"Provisions, dispatches, or creates a new Admin Unknown-devices Imei Ignore in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Unknown Devices"],"summary":"Create or Trigger Admin Unknown-devices Imei Ignore"}},"/api/admin/unknown-devices/{imei}/restore":{"post":{"description":"Provisions, dispatches, or creates a new Admin Unknown-devices Imei Restore in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Unknown Devices"],"summary":"Create or Trigger Admin Unknown-devices Imei Restore"}},"/api/admin/unknown-devices/{imei}":{"delete":{"description":"Permanently removes or unlinks the target Admin Unknown-devices Imei from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Unknown Devices"],"summary":"Delete Admin Unknown-devices Imei"}},"/api/admin/simulator/models":{"get":{"description":"Retrieves a paginated list of Admin Simulator Models accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Simulator"],"summary":"Get Admin Simulator Models"}},"/api/admin/simulator/sensor-types":{"get":{"description":"Retrieves a paginated list of Admin Simulator Sensor-types accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Simulator"],"summary":"Get Admin Simulator Sensor-types"}},"/api/admin/simulator/behaviors":{"get":{"description":"Retrieves a paginated list of Admin Simulator Behaviors accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Simulator"],"summary":"Get Admin Simulator Behaviors"}},"/api/admin/simulator/profiles":{"get":{"description":"Retrieves a paginated list of Admin Simulator Profiles accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Simulator"],"summary":"Get Admin Simulator Profiles"}},"/api/admin/simulator/generate-imei":{"post":{"description":"Provisions, dispatches, or creates a new Admin Simulator Generate-imei in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Simulator"],"summary":"Create or Trigger Admin Simulator Generate-imei"}},"/api/admin/simulator":{"get":{"description":"Checks whether the built-in GPS telemetry simulator is actively generating synthetic road movement for demonstration and stress testing.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Simulator run state."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Simulator"],"summary":"Get Status of Virtual GPS Hardware Simulator","security":[{"bearerAuth":[]}]},"post":{"description":"Launches a simulated tracker that feeds continuous realistic GPS packets along a simulated route to test live map rendering and alert rules.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Simulation started."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imei"],"properties":{"imei":{"type":"string","example":"999000000000001"},"speed":{"type":"number","default":60,"example":60},"interval_seconds":{"type":"integer","default":5,"example":5},"route":{"type":"string","enum":["dhaka_airport","chittagong_highway"],"example":"dhaka_airport"}}},"example":{"imei":"999000000000001","speed":60,"interval_seconds":5}}}},"tags":["Simulator"],"summary":"Start Virtual GPS Device Route Simulation","security":[{"bearerAuth":[]}]}},"/api/admin/simulator/{id}":{"put":{"description":"Updates and overwrites properties of the target Admin Simulator Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"example":"any"},"name":{"example":"any"},"model":{"example":"any"},"vehicle_profile":{"example":"any"},"behavior":{"example":"any"},"speed":{"example":"any"},"lat":{"example":"any"},"lon":{"example":"any"},"speed_min":{"example":"any"},"speed_max":{"example":"any"},"sensors":{"example":"any"},"route_points":{"example":"any"},"update_interval_ms":{"example":"any"},"jitter_percent":{"example":"any"},"error_mode":{"example":"any"},"connection_mode":{"example":"any"},"signal_quality":{"example":"any"}}}}}},"tags":["Simulator"],"summary":"Update Admin Simulator Id"},"delete":{"description":"Permanently removes or unlinks the target Admin Simulator Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Simulator"],"summary":"Delete Admin Simulator Id"}},"/api/admin/simulator/bulk":{"post":{"description":"Provisions, dispatches, or creates a new Admin Simulator Bulk in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"example":"any"}}}}}},"tags":["Simulator"],"summary":"Create or Trigger Admin Simulator Bulk"}},"/api/admin/simulator/bulk-create":{"post":{"description":"Provisions, dispatches, or creates a new Admin Simulator Bulk-create in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"example":"any"},"preset":{"example":"any"},"startLat":{"example":"any"},"startLon":{"example":"any"}}}}}},"tags":["Simulator"],"summary":"Create or Trigger Admin Simulator Bulk-create"}},"/api/admin/simulator/generate-route":{"post":{"description":"Provisions, dispatches, or creates a new Admin Simulator Generate-route in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"startLat":{"example":"any"},"startLon":{"example":"any"},"endLat":{"example":"any"},"endLon":{"example":"any"},"points":{"example":"any"}}}}}},"tags":["Simulator"],"summary":"Create or Trigger Admin Simulator Generate-route"}},"/api/favorites":{"get":{"description":"Retrieves a paginated list of Favorites accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Favorites"],"summary":"Get Favorites"}},"/api/favorites/ids":{"get":{"description":"Retrieves a paginated list of Favorites Ids accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Favorites"],"summary":"Get Favorites Ids"}},"/api/favorites/{imei}":{"post":{"description":"Provisions, dispatches, or creates a new Favorites Imei in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Favorites"],"summary":"Create or Trigger Favorites Imei"},"delete":{"description":"Permanently removes or unlinks the target Favorites Imei from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Favorites"],"summary":"Delete Favorites Imei"}},"/api/notification-profiles":{"get":{"description":"Retrieves a paginated list of Notification-profiles accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Profiles"],"summary":"Get Notification-profiles"},"post":{"description":"Provisions, dispatches, or creates a new Notification-profiles in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"user_ids":{"example":"any"}}}}}},"tags":["Notification Profiles"],"summary":"Create or Trigger Notification-profiles"}},"/api/notification-profiles/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Notification-profiles Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Profiles"],"summary":"Get Notification-profiles Id"},"put":{"description":"Updates and overwrites properties of the target Notification-profiles Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"user_ids":{"example":"any"}}}}}},"tags":["Notification Profiles"],"summary":"Update Notification-profiles Id"},"delete":{"description":"Permanently removes or unlinks the target Notification-profiles Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Profiles"],"summary":"Delete Notification-profiles Id"}},"/api/billing/balance":{"get":{"description":"Retrieves available prepaid coin balance, pending subscription renewals, and current coin consumption rate.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Balance and active device subscriptions count.","content":{"application/json":{"example":{"success":true,"data":{"coin_balance":1450,"active_subscriptions":42,"monthly_burn_rate":420,"days_remaining":103}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Organization Coin & Subscription Balance","security":[{"bearerAuth":[]}]}},"/api/billing/transactions":{"get":{"description":"Retrieves historical coin deposits, transfers between parent and child accounts, and monthly device renewal deductions.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Transaction history ledger."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"List Coin Balance Transaction Ledger","security":[{"bearerAuth":[]}]}},"/api/billing/transactions/export":{"get":{"description":"Retrieves a paginated list of Billing Transactions Export accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","produces":["text/csv"],"parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"},{"name":"type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Transactions Export"}},"/api/billing/settings":{"get":{"description":"Retrieves a paginated list of Billing Settings accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"org_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Settings"},"put":{"description":"Updates and overwrites properties of the target Billing Settings.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"example":"any"},"coin_validity_months":{"example":"any"},"allow_trial":{"example":"any"},"trial_duration_days":{"example":"any"},"auto_renew_on_expiry":{"example":"any"},"reset_to_inherited":{"example":"any"}}}}}},"tags":["Billing"],"summary":"Update Billing Settings"}},"/api/billing/trial-eligibility/{imei}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Billing Trial-eligibility Imei within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Trial-eligibility Imei"}},"/api/billing/admin/orgs/{id}/balance":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Billing Admin Orgs Id Balance within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Admin Orgs Id Balance"}},"/api/billing/admin/orgs/{id}/credit":{"post":{"description":"Provisions, dispatches, or creates a new Billing Admin Orgs Id Credit in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Billing"],"summary":"Create or Trigger Billing Admin Orgs Id Credit"}},"/api/billing/admin/orgs/{id}/deduct":{"post":{"description":"Provisions, dispatches, or creates a new Billing Admin Orgs Id Deduct in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Billing"],"summary":"Create or Trigger Billing Admin Orgs Id Deduct"}},"/api/billing/admin/orgs/{id}/transactions":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Billing Admin Orgs Id Transactions within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Admin Orgs Id Transactions"}},"/api/billing/admin/transactions":{"get":{"description":"Retrieves a paginated list of Billing Admin Transactions accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Admin Transactions"}},"/api/billing/admin/run-cron":{"post":{"description":"Provisions, dispatches, or creates a new Billing Admin Run-cron in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Create or Trigger Billing Admin Run-cron"}},"/api/billing/admin/renewal-summary":{"get":{"description":"Retrieves a paginated list of Billing Admin Renewal-summary accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Admin Renewal-summary"}},"/api/billing/transfer":{"post":{"description":"Provisions, dispatches, or creates a new Billing Transfer in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"target_org_id":{"example":"any"},"amount":{"example":"any"},"idempotency_key":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Billing"],"summary":"Create or Trigger Billing Transfer"}},"/api/billing/recall":{"post":{"description":"Provisions, dispatches, or creates a new Billing Recall in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"target_org_id":{"example":"any"},"amount":{"example":"any"},"idempotency_key":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Billing"],"summary":"Create or Trigger Billing Recall"}},"/api/billing/hierarchy-balances":{"get":{"description":"Retrieves a paginated list of Billing Hierarchy-balances accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Billing"],"summary":"Get Billing Hierarchy-balances"}},"/api/billing/admin/mint":{"post":{"description":"Provisions, dispatches, or creates a new Billing Admin Mint in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Billing"],"summary":"Create or Trigger Billing Admin Mint"}},"/api/devices/bulk/import":{"post":{"description":"Provisions hundreds or thousands of GPS tracking units in a single batch transaction. Validates IMEI checksums, assigns default fleets, models, and SIM cards, and reports validation errors row-by-row.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Batch intake summary with imported and skipped counts.","content":{"application/json":{"example":{"success":true,"data":{"imported":2,"failed":0,"errors":[]}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"402":{"description":"Payment Required"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["devices"],"properties":{"devices":{"type":"array","items":{"type":"object","required":["imei","name"],"properties":{"imei":{"type":"string","example":"864540081293581"},"name":{"type":"string","example":"Van 101"},"model":{"type":"string","example":"GT06Pro"},"plate_number":{"type":"string","example":"DHK-11-2041"},"fleet_id":{"type":"integer","example":14}}}}}},"example":{"devices":[{"imei":"864540081293581","name":"Van 101","model":"GT06Pro","plate_number":"DHK-11-2041","fleet_id":14},{"imei":"865167047241865","name":"Van 102","model":"GT06Pro","plate_number":"DHK-11-2042","fleet_id":14}]}}}},"tags":["Bulk Operations"],"summary":"Bulk Import Devices from CSV / JSON Dataset","security":[{"bearerAuth":[]}]}},"/api/devices/bulk/assign-fleet":{"post":{"description":"Transfers an array of vehicle devices to a specific fleet or sub-fleet group in one operation.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Devices assigned to fleet."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imeis","fleet_id"],"properties":{"imeis":{"type":"array","items":{"type":"string"},"example":["864540081293581","865167047241865"]},"fleet_id":{"type":"integer","example":14}}},"example":{"imeis":["864540081293581","865167047241865"],"fleet_id":14}}}},"tags":["Bulk Operations"],"summary":"Batch Assign Multiple Devices to Fleet Group","security":[{"bearerAuth":[]}]}},"/api/devices/bulk/assign-org":{"post":{"description":"Provisions, dispatches, or creates a new Devices Bulk Assign-org in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"},"org_id":{"example":"any"}}}}}},"tags":["Bulk Operations"],"summary":"Create or Trigger Devices Bulk Assign-org"}},"/api/devices/bulk/status":{"post":{"description":"Provisions, dispatches, or creates a new Devices Bulk Status in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"},"active":{"example":"any"}}}}}},"tags":["Bulk Operations"],"summary":"Create or Trigger Devices Bulk Status"}},"/api/devices/bulk/delete":{"post":{"description":"Removes an array of devices from the tenant organization in a single transaction. Historical data is archived.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Batch deletion complete."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imeis"],"properties":{"imeis":{"type":"array","items":{"type":"string"},"example":["864540081293581"]}}},"example":{"imeis":["864540081293581"]}}}},"tags":["Bulk Operations"],"summary":"Batch Delete Devices from Inventory","security":[{"bearerAuth":[]}]}},"/api/devices/bulk/templates/users":{"get":{"description":"Retrieves a paginated list of Devices Bulk Templates Users accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Operations"],"summary":"Get Devices Bulk Templates Users"}},"/api/devices/bulk/templates/devices":{"get":{"description":"Returns the formatted header structure and sample rows required for bulk CSV device intake.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"CSV file download or column specification."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Operations"],"summary":"Download Standard CSV Template for Device Import","security":[{"bearerAuth":[]}]}},"/api/bulk/import":{"post":{"description":"Provisions, dispatches, or creates a new Bulk Import in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"402":{"description":"Payment Required"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"devices":{"example":"any"}}}}}},"tags":["Bulk Operations"],"summary":"Create or Trigger Bulk Import"}},"/api/bulk/assign-fleet":{"post":{"description":"Provisions, dispatches, or creates a new Bulk Assign-fleet in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"},"fleet_id":{"example":"any"}}}}}},"tags":["Bulk Operations"],"summary":"Create or Trigger Bulk Assign-fleet"}},"/api/bulk/assign-org":{"post":{"description":"Provisions, dispatches, or creates a new Bulk Assign-org in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"},"org_id":{"example":"any"}}}}}},"tags":["Bulk Operations"],"summary":"Create or Trigger Bulk Assign-org"}},"/api/bulk/status":{"post":{"description":"Provisions, dispatches, or creates a new Bulk Status in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"},"active":{"example":"any"}}}}}},"tags":["Bulk Operations"],"summary":"Create or Trigger Bulk Status"}},"/api/bulk/delete":{"post":{"description":"Provisions, dispatches, or creates a new Bulk Delete in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imeis":{"example":"any"}}}}}},"tags":["Bulk Operations"],"summary":"Create or Trigger Bulk Delete"}},"/api/bulk/templates/users":{"get":{"description":"Retrieves a paginated list of Bulk Templates Users accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Operations"],"summary":"Get Bulk Templates Users"}},"/api/bulk/templates/devices":{"get":{"description":"Retrieves a paginated list of Bulk Templates Devices accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Operations"],"summary":"Get Bulk Templates Devices"}},"/api/admin/security/access-logs":{"get":{"description":"Retrieves a paginated list of Admin Security Access-logs accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"user_id","in":"query","schema":{"type":"string"}},{"name":"event_type","in":"query","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Get Admin Security Access-logs"}},"/api/admin/security/api-logs":{"get":{"description":"Retrieves a paginated list of Admin Security Api-logs accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"org_id","in":"query","schema":{"type":"string"}},{"name":"method","in":"query","schema":{"type":"string"}},{"name":"path","in":"query","schema":{"type":"string"}},{"name":"user_id","in":"query","schema":{"type":"string"}},{"name":"entity_type","in":"query","schema":{"type":"string"}},{"name":"mutations_only","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string","example":"Toyota"},"description":"Search filter keyword"},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Get Admin Security Api-logs"}},"/api/admin/security/device-audit-logs":{"get":{"description":"Retrieves a paginated list of Admin Security Device-audit-logs accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"org_id","in":"query","schema":{"type":"string"}},{"name":"device_imei","in":"query","schema":{"type":"string"}},{"name":"user_id","in":"query","schema":{"type":"string"}},{"name":"action","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string","example":"Toyota"},"description":"Search filter keyword"},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Get Admin Security Device-audit-logs"}},"/api/admin/security/command-logs":{"get":{"description":"Retrieves a paginated list of Admin Security Command-logs accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"org_id","in":"query","schema":{"type":"string"}},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"user_id","in":"query","schema":{"type":"string"}},{"name":"command_type","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"channel","in":"query","schema":{"type":"string","example":1},"description":"Camera video channel number (1-8)"},{"name":"search","in":"query","schema":{"type":"string","example":"Toyota"},"description":"Search filter keyword"},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Get Admin Security Command-logs"}},"/api/admin/security/export":{"get":{"description":"Retrieves a paginated list of Admin Security Export accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","produces":["text/csv; charset=utf-8"],"parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"org_id","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string","example":"Toyota"},"description":"Search filter keyword"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Get Admin Security Export"}},"/api/admin/security/api-analytics":{"get":{"description":"Retrieves a paginated list of Admin Security Api-analytics accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"days","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Get Admin Security Api-analytics"}},"/api/admin/security/sessions":{"get":{"description":"Retrieves a paginated list of Admin Security Sessions accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Get Admin Security Sessions"}},"/api/admin/security/sessions/{id}":{"delete":{"description":"Permanently removes or unlinks the target Admin Security Sessions Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Security"],"summary":"Delete Admin Security Sessions Id"}},"/api/admin/ip-management/blocked":{"get":{"description":"Retrieves a paginated list of Admin Ip-management Blocked accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["IP Management"],"summary":"Get Admin Ip-management Blocked"}},"/api/admin/ip-management/unblock":{"post":{"description":"Provisions, dispatches, or creates a new Admin Ip-management Unblock in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ip":{"example":"any"},"type":{"example":"any"}}}}}},"tags":["IP Management"],"summary":"Create or Trigger Admin Ip-management Unblock"}},"/api/admin/ip-management/blacklist":{"get":{"description":"Retrieves a paginated list of Admin Ip-management Blacklist accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["IP Management"],"summary":"Get Admin Ip-management Blacklist"},"post":{"description":"Provisions, dispatches, or creates a new Admin Ip-management Blacklist in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ip":{"example":"any"},"reason":{"example":"any"}}}}}},"tags":["IP Management"],"summary":"Create or Trigger Admin Ip-management Blacklist"}},"/api/admin/ip-management/blacklist/{ip}":{"delete":{"description":"Permanently removes or unlinks the target Admin Ip-management Blacklist Ip from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"ip","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["IP Management"],"summary":"Delete Admin Ip-management Blacklist Ip"}},"/api/admin/system-stats":{"get":{"description":"Retrieves a paginated list of Admin System-stats accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Admin Diagnostics"],"summary":"Get Admin System-stats"}},"/api/roles/permissions":{"get":{"description":"Retrieves a paginated list of Roles Permissions accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Roles"],"summary":"Get Roles Permissions"}},"/api/roles/templates":{"get":{"description":"Retrieves a paginated list of Roles Templates accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Roles"],"summary":"Get Roles Templates"}},"/api/roles":{"get":{"description":"Retrieves standard system roles (Platform Admin, Admin, Manager, Viewer, Driver) and custom tenant roles with granular permission scopes.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of roles and permission matrices."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Roles"],"summary":"List Available RBAC Roles & Permissions","security":[{"bearerAuth":[]}]},"post":{"description":"Creates a customized role specifying exact permissions for devices, tracking, alerts, geofences, commands, reports, and billing.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Custom role created."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"permissions":{"example":"any"},"template":{"example":"any"}}}}}},"tags":["Roles"],"summary":"Create Custom Role with Granular Permissions","security":[{"bearerAuth":[]}]}},"/api/roles/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Roles Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Roles"],"summary":"Get Roles Id"},"put":{"description":"Updates and overwrites properties of the target Roles Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"permissions":{"example":"any"}}}}}},"tags":["Roles"],"summary":"Update Roles Id"},"delete":{"description":"Permanently removes or unlinks the target Roles Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Roles"],"summary":"Delete Roles Id"}},"/api/roles/{id}/assign":{"post":{"description":"Provisions, dispatches, or creates a new Roles Id Assign in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userIds":{"example":"any"}}}}}},"tags":["Roles"],"summary":"Create or Trigger Roles Id Assign"}},"/api/roles/{id}/unassign":{"post":{"description":"Provisions, dispatches, or creates a new Roles Id Unassign in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userIds":{"example":"any"}}}}}},"tags":["Roles"],"summary":"Create or Trigger Roles Id Unassign"}},"/api/settings/public":{"get":{"description":"Retrieves a paginated list of Settings Public accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Settings"],"summary":"Get Settings Public"}},"/api/settings/status-thresholds":{"get":{"description":"Retrieves a paginated list of Settings Status-thresholds accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Settings"],"summary":"Get Settings Status-thresholds"},"put":{"description":"Updates and overwrites properties of the target Settings Status-thresholds.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"min_moving_speed_kmh":{"example":"any"},"online_timeout_minutes":{"example":"any"},"min_trip_duration_seconds":{"example":"any"},"min_parking_duration_seconds":{"example":"any"},"ignition_debounce_seconds":{"example":"any"}}}}}},"tags":["Settings"],"summary":"Update Settings Status-thresholds"}},"/api/settings":{"get":{"description":"Retrieves a paginated list of Settings accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Settings"],"summary":"Get Settings"}},"/api/settings/{key}":{"put":{"description":"Updates and overwrites properties of the target Settings Key.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","example":"battery_level"},"description":"Attribute or preference setting key"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"example":"any"}}}}}},"tags":["Settings"],"summary":"Update Settings Key"}},"/api/payments/plans":{"get":{"description":"Retrieves a paginated list of Payments Plans accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Payments"],"summary":"Get Payments Plans"}},"/api/payments/collect-cash":{"post":{"description":"Provisions, dispatches, or creates a new Payments Collect-cash in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"example":"any"},"plan_id":{"example":"any"},"amount":{"example":"any"},"coins":{"example":"any"},"currency":{"example":"any"},"payment_method":{"example":"any"},"reference":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Payments"],"summary":"Create or Trigger Payments Collect-cash"}},"/api/payments/history":{"get":{"description":"Retrieves a paginated list of Payments History accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Payments"],"summary":"Get Payments History"}},"/api/payments/subscription":{"get":{"description":"Retrieves a paginated list of Payments Subscription accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Payments"],"summary":"Get Payments Subscription"}},"/api/payments/admin/plans":{"post":{"description":"Provisions, dispatches, or creates a new Payments Admin Plans in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"price":{"example":"any"},"currency":{"example":"any"},"interval":{"example":"any"},"device_limit":{"example":"any"},"coin_value":{"example":"any"},"features":{"example":"any"},"is_default":{"example":"any"},"sort_order":{"example":"any"},"org_id":{"example":"any"}}}}}},"tags":["Payments"],"summary":"Create or Trigger Payments Admin Plans"}},"/api/payments/admin/plans/{id}":{"put":{"description":"Updates and overwrites properties of the target Payments Admin Plans Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"price":{"example":"any"},"currency":{"example":"any"},"interval":{"example":"any"},"device_limit":{"example":"any"},"coin_value":{"example":"any"},"features":{"example":"any"},"is_default":{"example":"any"},"active":{"example":"any"},"sort_order":{"example":"any"}}}}}},"tags":["Payments"],"summary":"Update Payments Admin Plans Id"},"delete":{"description":"Permanently removes or unlinks the target Payments Admin Plans Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Payments"],"summary":"Delete Payments Admin Plans Id"}},"/api/payments/admin/revenue":{"get":{"description":"Retrieves a paginated list of Payments Admin Revenue accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Payments"],"summary":"Get Payments Admin Revenue"}},"/api/payments/admin/transactions":{"get":{"description":"Retrieves a paginated list of Payments Admin Transactions accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"gateway","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Payments"],"summary":"Get Payments Admin Transactions"}},"/api/custom-fields":{"get":{"description":"Retrieves extensible custom fields configured for entities (Vehicles, Users, Fleets, Drivers) such as Insurance Policy Number, Vehicle Color, or Road Tax Expiry.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"entity_type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of custom field definitions."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Custom Fields"],"summary":"List Dynamic Custom Schema Fields","security":[{"bearerAuth":[]}]},"post":{"description":"Creates an extra schema attribute on an entity type with validation constraints (text, number, date, dropdown).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Custom field registered."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["field_name","entity_type","field_type"],"properties":{"field_name":{"type":"string","description":"Internal field identifier (or pass as \"name\")","example":"fitness_cert_expiry"},"name":{"type":"string","description":"Alias for field_name","example":"fitness_cert_expiry"},"field_label":{"type":"string","description":"User-facing label","example":"Fitness Certificate Expiry"},"entity_type":{"type":"string","enum":["device","driver","fleet","user","geofence"],"example":"device"},"field_type":{"type":"string","enum":["text","number","date","select","boolean"],"description":"Data type (or pass as \"data_type\")","example":"date"},"data_type":{"type":"string","enum":["text","number","date","select","boolean"],"description":"Alias for field_type","example":"date"},"options":{"type":"array","items":{"type":"string"},"description":"Dropdown options if field_type is select","example":["Option A","Option B"]},"is_required":{"type":"boolean","default":false,"example":false}}},"example":{"field_name":"fitness_cert_expiry","field_label":"Fitness Certificate Expiry","entity_type":"device","field_type":"date","is_required":false}}}},"tags":["Custom Fields"],"summary":"Define New Dynamic Custom Field","security":[{"bearerAuth":[]}]}},"/api/custom-fields/search":{"get":{"description":"Retrieves a paginated list of Custom-fields Search accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"entity_type","in":"query","schema":{"type":"string"}},{"name":"field_id","in":"query","schema":{"type":"string"}},{"name":"value","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Custom Fields"],"summary":"Get Custom-fields Search"}},"/api/custom-fields/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Custom-fields Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Custom Fields"],"summary":"Get Custom-fields Id"},"put":{"description":"Updates and overwrites properties of the target Custom-fields Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"field_name":{"example":"any"},"field_type":{"example":"any"},"options":{"example":"any"},"required":{"example":"any"},"sort_order":{"example":"any"}}}}}},"tags":["Custom Fields"],"summary":"Update Custom-fields Id"},"delete":{"description":"Permanently removes or unlinks the target Custom-fields Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Custom Fields"],"summary":"Delete Custom-fields Id"}},"/api/custom-fields/reorder":{"put":{"description":"Updates and overwrites properties of the target Custom-fields Reorder.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"field_orders":{"example":"any"}}}}}},"tags":["Custom Fields"],"summary":"Update Custom-fields Reorder"}},"/api/custom-fields/values/{entity_type}/bulk":{"get":{"description":"Retrieves a paginated list of Custom-fields Values Entity_type Bulk accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"entity_type","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"entity_ids","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Custom Fields"],"summary":"Get Custom-fields Values Entity_type Bulk"}},"/api/custom-fields/values/{entity_type}/{entity_id}":{"get":{"description":"Retrieves a paginated list of Custom-fields Values Entity_type Entity_id accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"entity_type","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Custom Fields"],"summary":"Get Custom-fields Values Entity_type Entity_id"},"put":{"description":"Updates and overwrites properties of the target Custom-fields Values Entity_type Entity_id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"entity_type","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"values":{"example":"any"}}}}}},"tags":["Custom Fields"],"summary":"Update Custom-fields Values Entity_type Entity_id"}},"/api/notification-templates":{"get":{"description":"Retrieves predefined message templates used across Email, SMS, WhatsApp, and FCM Push with dynamic variables (e.g. {{vehicle_name}}, {{speed}}, {{address}}).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"channel","in":"query","schema":{"type":"string","example":1},"description":"Camera video channel number (1-8)"}],"responses":{"200":{"description":"List of notification templates."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Templates"],"summary":"List Multi-Channel Notification Templates","security":[{"bearerAuth":[]}]},"post":{"description":"Creates a new customizable message template for specific alert triggers (e.g. overspeed, geofence_enter, geofence_exit, sos, fuel_theft).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Notification template created."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channel","event_type","body"],"properties":{"channel":{"type":"string","enum":["email","sms","push"],"description":"Notification delivery channel","example":"sms"},"event_type":{"type":"string","enum":["overspeed","geofence_enter","geofence_exit","sos","offline","fuel_theft","deviceMoving","deviceStopped","deviceEngineIdle","route_deviation","default"],"description":"Trigger event type","example":"overspeed"},"name":{"type":"string","description":"Template display name (alias for event_type if event_type is omitted)","example":"Overspeed SMS Template"},"subject":{"type":"string","description":"Email/Push subject heading","example":"Speed Alert: {{device_name}}"},"body":{"type":"string","description":"Template message body supporting dynamic variables","example":"Alert: {{device_name}} exceeded {{speed_limit}} km/h at {{location}}."}}},"example":{"channel":"sms","event_type":"overspeed","body":"Alert: {{device_name}} exceeded {{speed_limit}} km/h at {{location}}."}}}},"tags":["Notification Templates"],"summary":"Create Notification Message Template","security":[{"bearerAuth":[]}]}},"/api/notification-templates/variables":{"get":{"description":"Retrieves a paginated list of Notification-templates Variables accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Templates"],"summary":"Get Notification-templates Variables"}},"/api/notification-templates/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Notification-templates Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Templates"],"summary":"Get Notification-templates Id"},"put":{"description":"Updates and overwrites properties of the target Notification-templates Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"example":"any"},"body":{"example":"any"},"active":{"example":"any"}}}}}},"tags":["Notification Templates"],"summary":"Update Notification-templates Id"},"delete":{"description":"Permanently removes or unlinks the target Notification-templates Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Templates"],"summary":"Delete Notification-templates Id"}},"/api/notification-templates/preview":{"post":{"description":"Provisions, dispatches, or creates a new Notification-templates Preview in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"example":"any"},"body":{"example":"any"},"event_type":{"example":"any"}}}}}},"tags":["Notification Templates"],"summary":"Create or Trigger Notification-templates Preview"}},"/api/notification-templates/{id}/reset":{"post":{"description":"Provisions, dispatches, or creates a new Notification-templates Id Reset in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notification Templates"],"summary":"Create or Trigger Notification-templates Id Reset"}},"/api/domains":{"get":{"description":"Retrieves custom domains onboarded for white-label branding, including SSL/TLS certificate status and DNS CNAME verification.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of custom domains."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Domains"],"summary":"List Custom White-Label CNAME Domains","security":[{"bearerAuth":[]}]},"post":{"description":"Provisions a new custom tracking domain (e.g. `gps.xeekar.com`) and initiates automated Caddy Let's Encrypt SSL/TLS verification.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"201":{"description":"Domain added; DNS CNAME target returned."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","example":"gps.xeekar.com"}}},"example":{"domain":"gps.xeekar.com"}}}},"tags":["Domains"],"summary":"Add Custom Domain for White-Label Access","security":[{"bearerAuth":[]}]},"delete":{"description":"Permanently removes or unlinks the target Domains from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Domains"],"summary":"Delete Domains"}},"/api/domains/verify":{"post":{"description":"Provisions, dispatches, or creates a new Domains Verify in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Domains"],"summary":"Create or Trigger Domains Verify"}},"/api/domains/check-dns":{"post":{"description":"Provisions, dispatches, or creates a new Domains Check-dns in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"host":{"example":"any"},"expectedType":{"example":"any"},"recordHost":{"example":"any"}}}}}},"tags":["Domains"],"summary":"Create or Trigger Domains Check-dns"}},"/api/domains/check-all-dns":{"post":{"description":"Provisions, dispatches, or creates a new Domains Check-all-dns in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Domains"],"summary":"Create or Trigger Domains Check-all-dns"}},"/api/chat/rooms":{"get":{"description":"Retrieves a paginated list of Chat Rooms accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Chat"],"summary":"Get Chat Rooms"}},"/api/chat/rooms/{roomId}/messages":{"get":{"description":"Retrieves a paginated list of Chat Rooms RoomId Messages accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string","example":"room-14-dispatch"},"description":"Chat conversation room identifier"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Chat"],"summary":"Get Chat Rooms RoomId Messages"},"post":{"description":"Provisions, dispatches, or creates a new Chat Rooms RoomId Messages in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string","example":"room-14-dispatch"},"description":"Chat conversation room identifier"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"example":"any"},"receiverId":{"example":"any"}}}}}},"tags":["Chat"],"summary":"Create or Trigger Chat Rooms RoomId Messages"}},"/api/notifications":{"get":{"description":"Retrieves in-app notification center inbox for the authenticated user, including read status, timestamp, and alert payload.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"unread","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of in-app notifications."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notifications"],"summary":"List User In-App Notifications & Alerts Inbox","security":[{"bearerAuth":[]}]}},"/api/notifications/unread-count":{"get":{"description":"Returns the count of unread alert notifications to display on the dashboard bell badge.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Unread notification count.","content":{"application/json":{"example":{"count":3}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notifications"],"summary":"Get Count of Unread Notifications","security":[{"bearerAuth":[]}]}},"/api/notifications/read-all":{"put":{"description":"Clears unread indicators by marking all notification inbox messages as read for the user.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"All notifications marked as read."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"example":"any"}}}}}},"tags":["Notifications"],"summary":"Mark All Notifications as Read","security":[{"bearerAuth":[]}]}},"/api/notifications/{id}/read":{"put":{"description":"Updates and overwrites properties of the target Notifications Id Read.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notifications"],"summary":"Update Notifications Id Read"}},"/api/notifications/batch":{"delete":{"description":"Permanently removes or unlinks the target Notifications Batch from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"example":"any"},"all":{"example":"any"},"category":{"example":"any"}}}}}},"tags":["Notifications"],"summary":"Delete Notifications Batch"}},"/api/notifications/batch-delete":{"post":{"description":"Provisions, dispatches, or creates a new Notifications Batch-delete in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"example":"any"},"all":{"example":"any"},"category":{"example":"any"}}}}}},"tags":["Notifications"],"summary":"Create or Trigger Notifications Batch-delete"}},"/api/notifications/{id}":{"delete":{"description":"Permanently removes or unlinks the target Notifications Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Notifications"],"summary":"Delete Notifications Id"}},"/api/inspections/templates":{"get":{"description":"Retrieves a paginated list of Inspections Templates accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Inspections"],"summary":"Get Inspections Templates"},"post":{"description":"Provisions, dispatches, or creates a new Inspections Templates in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"type":{"example":"any"},"items":{"example":"any"}}}}}},"tags":["Inspections"],"summary":"Create or Trigger Inspections Templates"}},"/api/inspections/templates/{id}":{"put":{"description":"Updates and overwrites properties of the target Inspections Templates Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"description":{"example":"any"},"type":{"example":"any"},"active":{"example":"any"},"items":{"example":"any"}}}}}},"tags":["Inspections"],"summary":"Update Inspections Templates Id"},"delete":{"description":"Permanently removes or unlinks the target Inspections Templates Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Inspections"],"summary":"Delete Inspections Templates Id"}},"/api/inspections/stats":{"get":{"description":"Retrieves a paginated list of Inspections Stats accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Inspections"],"summary":"Get Inspections Stats"}},"/api/inspections":{"get":{"description":"Retrieves driver vehicle inspection reports (DVIR checklists) covering tire condition, lights, brakes, windshield, fluid levels, and reported defects.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"template_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of inspection checklist submissions."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Inspections"],"summary":"List Pre-Trip & Post-Trip Vehicle Inspections (DVIR)","security":[{"bearerAuth":[]}]},"post":{"description":"Submits an electronic inspection report completed by the driver prior to departure or after shift completion.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Inspection recorded successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_id"],"properties":{"device_id":{"type":"string","description":"Device IMEI (or pass as imei)","example":"864540081293581"},"imei":{"type":"string","description":"Alias for device_id","example":"864540081293581"},"template_id":{"type":"string","format":"uuid","description":"Checklist template UUID (optional, defaults to org template)","example":"550e8400-e29b-41d4-a716-446655440000"},"passed":{"type":"boolean","description":"Quick pass/fail overall indicator","example":true},"odometer":{"type":"number","example":18450},"responses":{"type":"array","description":"Detailed checklist question responses","items":{"type":"object","required":["result"],"properties":{"item_id":{"type":"string","format":"uuid","description":"Item UUID"},"result":{"type":"string","enum":["pass","fail","na"],"example":"pass"},"notes":{"type":"string","example":"Good"}}}},"items":{"type":"object","description":"Key-value map of items (convenience alias for responses)","example":{"brakes":"pass","tires":"pass","lights":"pass","horn":"pass"}},"notes":{"type":"string","example":"Pre-trip check complete"}}},"example":{"imei":"864540081293581","passed":true,"odometer":18450,"items":{"brakes":"pass","tires":"pass"}}}}},"tags":["Inspections"],"summary":"Submit Vehicle Inspection Checklist (DVIR)","security":[{"bearerAuth":[]}]}},"/api/inspections/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Inspections Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Inspections"],"summary":"Get Inspections Id"}},"/api/expenses":{"get":{"description":"Retrieves vehicle expenses (fuel purchase, toll fees, parking, traffic fines, maintenance) with receipt image URLs and category totals.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"device_imei","in":"query","schema":{"type":"string"}},{"name":"imei","in":"query","schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"date_from","in":"query","schema":{"type":"string"}},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"},{"name":"date_to","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string","example":"Toyota"},"description":"Search filter keyword"}],"responses":{"200":{"description":"List of recorded expenses."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Expenses"],"summary":"List Fleet Operational Expenses & Fuel Receipts","security":[{"bearerAuth":[]}]},"post":{"description":"Logs an expenditure incurred by a vehicle or driver during commercial operations.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Expense saved."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["category","amount"],"properties":{"device_id":{"type":"string","description":"Vehicle device IMEI (or pass as imei)","example":"864540081293581"},"imei":{"type":"string","description":"Alias for device_id","example":"864540081293581"},"category":{"type":"string","enum":["fuel","toll","parking","maintenance","fine","other"],"example":"toll"},"amount":{"type":"number","example":350},"currency":{"type":"string","default":"BDT","example":"BDT"},"notes":{"type":"string","example":"Padma Bridge Toll"}}},"example":{"imei":"864540081293581","category":"toll","amount":350,"notes":"Padma Bridge Toll"}}}},"tags":["Expenses"],"summary":"Record Vehicle Expense Entry","security":[{"bearerAuth":[]}]}},"/api/expenses/summary":{"get":{"description":"Retrieves a paginated list of Expenses Summary accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"date_from","in":"query","schema":{"type":"string"}},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"},{"name":"date_to","in":"query","schema":{"type":"string"}},{"name":"device_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Expenses"],"summary":"Get Expenses Summary"}},"/api/expenses/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Expenses Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Expenses"],"summary":"Get Expenses Id"},"put":{"description":"Updates and overwrites properties of the target Expenses Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_id":{"example":"any"},"device_imei":{"example":"any"},"type":{"example":"any"},"category":{"example":"any"},"amount":{"example":"any"},"liters":{"example":"any"},"currency":{"example":"any"},"date":{"example":"any"},"description":{"example":"any"},"notes":{"example":"any"},"receipt_url":{"example":"any"},"receipt_attachment":{"example":"any"},"payment_method":{"example":"any"},"vendor":{"example":"any"},"reference_number":{"example":"any"},"odometer":{"example":"any"}}}}}},"tags":["Expenses"],"summary":"Update Expenses Id"},"patch":{"description":"Applies partial field modifications to the target Expenses Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_id":{"example":"any"},"device_imei":{"example":"any"},"type":{"example":"any"},"category":{"example":"any"},"amount":{"example":"any"},"liters":{"example":"any"},"currency":{"example":"any"},"date":{"example":"any"},"description":{"example":"any"},"notes":{"example":"any"},"receipt_url":{"example":"any"},"receipt_attachment":{"example":"any"},"payment_method":{"example":"any"},"vendor":{"example":"any"},"reference_number":{"example":"any"},"odometer":{"example":"any"}}}}}},"tags":["Expenses"],"summary":"Modify Expenses Id"},"delete":{"description":"Permanently removes or unlinks the target Expenses Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Expenses"],"summary":"Delete Expenses Id"}},"/api/expenses/analyze-receipt":{"post":{"description":"Provisions, dispatches, or creates a new Expenses Analyze-receipt in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"422":{"description":"Unprocessable Entity"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"example":"any"},"image_base64":{"example":"any"},"image_url":{"example":"any"}}}}}},"tags":["Expenses"],"summary":"Create or Trigger Expenses Analyze-receipt"}},"/api/bulk-tanks":{"get":{"description":"Retrieves inventory of stationary depot fuel tanks, including current fuel volume, capacity, calibrated sensor port, and fuel type (Diesel, Petrol, Octane, Jet-A1).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of bulk tanks and current fuel stocks.","content":{"application/json":{"example":{"success":true,"data":[{"id":"tank-01","name":"Depot Yard Diesel Tank A","fuel_type":"diesel","capacity_liters":25000,"current_volume_liters":18450,"percent_full":73.8,"sensor_imei":"865167047241865"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Fuel Tanks"],"summary":"List Yard Bulk Fuel Tanks & Stationary Storage","security":[{"bearerAuth":[]}]},"post":{"description":"Adds a stationary depot bulk tank with calibrated tank dimensions and optional IoT level sensor probe.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Bulk tank created successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","capacity_liters","fuel_type"],"properties":{"name":{"type":"string","example":"Depot Yard Diesel Tank B"},"capacity_liters":{"type":"number","example":30000},"fuel_type":{"type":"string","enum":["diesel","petrol","octane","cng","lpg"],"example":"diesel"},"sensor_imei":{"type":"string","example":"865167047241865"}}},"example":{"name":"Depot Yard Diesel Tank B","capacity_liters":30000,"fuel_type":"diesel"}}}},"tags":["Bulk Fuel Tanks"],"summary":"Register New Yard Bulk Fuel Tank","security":[{"bearerAuth":[]}]}},"/api/bulk-tanks/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Bulk-tanks Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Fuel Tanks"],"summary":"Get Bulk-tanks Id"},"put":{"description":"Updates and overwrites properties of the target Bulk-tanks Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"location":{"example":"any"},"fuel_type":{"example":"any"},"capacity_liters":{"example":"any"},"current_liters":{"example":"any"},"alert_low_liters":{"example":"any"},"dipstick_calibration":{"example":"any"}}}}}},"tags":["Bulk Fuel Tanks"],"summary":"Update Bulk-tanks Id"},"delete":{"description":"Permanently removes or unlinks the target Bulk-tanks Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Fuel Tanks"],"summary":"Delete Bulk-tanks Id"}},"/api/bulk-tanks/{id}/logs":{"get":{"description":"Retrieves delivery intake logs (tanker refill) and vehicle dispensation transactions from this stationary tank.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"tank-01"},"description":"Bulk tank ID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"Dispensation and intake logs."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Bulk Fuel Tanks"],"summary":"Get Bulk Tank Fuel Intake & Dispensation Ledger","security":[{"bearerAuth":[]}]},"post":{"description":"Records a fuel dispensation to a specific fleet vehicle or intake delivery from an oil marketing company.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"tank-01"},"description":"Bulk tank ID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Fuel transaction logged."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["transaction_type","liters"],"properties":{"transaction_type":{"type":"string","enum":["dispense","refill"],"example":"dispense"},"liters":{"type":"number","example":120},"vehicle_imei":{"type":"string","example":"864540081293581"},"driver_name":{"type":"string","example":"Rahim Khan"},"cost_per_liter":{"type":"number","example":105}}},"example":{"transaction_type":"dispense","liters":120,"vehicle_imei":"864540081293581","driver_name":"Rahim Khan"}}}},"tags":["Bulk Fuel Tanks"],"summary":"Record Fuel Dispensation or Refill Log","security":[{"bearerAuth":[]}]}},"/api/weather":{"get":{"description":"Fetches real-time ambient weather (temperature, humidity, precipitation, wind speed, visibility) for vehicle latitude and longitude coordinates.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"lat","in":"query","schema":{"type":"number","example":23.8103},"required":true,"description":"Latitude coordinate"},{"name":"lon","in":"query","schema":{"type":"number","example":90.4125},"required":true,"description":"Longitude coordinate"}],"responses":{"200":{"description":"Live atmospheric conditions.","content":{"application/json":{"example":{"temp_c":29.5,"condition":"Partly Cloudy","humidity":72,"wind_kph":14.2}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"502":{"description":"Bad Gateway"},"503":{"description":"Service Unavailable"}},"tags":["Weather"],"summary":"Get Live Weather & Atmospheric Conditions for Coordinates","security":[{"bearerAuth":[]}]}},"/api/fuel-prices/nearest":{"get":{"description":"Retrieves current retail prices per liter for Diesel, Octane, Petrol, and CNG for fleet fuel cost calculation based on latitude and longitude coordinates (defaults to Dhaka if omitted).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"lat","in":"query","schema":{"type":"number","example":23.8103},"description":"Vehicle latitude (defaults to 23.8103)"},{"name":"lon","in":"query","schema":{"type":"number","example":90.4125},"description":"Vehicle longitude (defaults to 90.4125)"}],"responses":{"200":{"description":"Current fuel prices per liter.","content":{"application/json":{"example":{"success":true,"data":{"city":"Dhaka","state":"Dhaka","petrol":125,"diesel":105,"cng":43,"octane":130,"lpg":100,"date":"2026-10-11"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fuel Prices"],"summary":"Get Current Government / Market Fuel Prices Near Location","security":[{"bearerAuth":[]}]}},"/api/fuel-prices":{"get":{"description":"Retrieves current retail prices per liter for Diesel, Octane, Petrol, and CNG for fleet fuel cost calculation (defaults to capital / base city).","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"lat","in":"query","schema":{"type":"number","example":23.8103},"description":"Vehicle latitude (defaults to 23.8103)"},{"name":"lon","in":"query","schema":{"type":"number","example":90.4125},"description":"Vehicle longitude (defaults to 90.4125)"}],"responses":{"200":{"description":"Current fuel prices per liter.","content":{"application/json":{"example":{"success":true,"data":{"city":"Dhaka","state":"Dhaka","petrol":125,"diesel":105,"cng":43,"octane":130,"lpg":100,"date":"2026-10-11"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Fuel Prices"],"summary":"Get Current Government / Market Fuel Prices","security":[{"bearerAuth":[]}]}},"/api/ai/query":{"post":{"description":"Ask natural language questions about your fleet (e.g. \"Which vehicle drove the most kilometers this week?\", \"Did any vehicle leave Dhaka after 10 PM?\", \"Show top 3 fuel consumers\"). The AI agent converts the prompt into SQL/analytics queries and returns structured data and insights.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"AI-generated fleet answer with underlying telematics data.","content":{"application/json":{"example":{"answer":"Toyota Allion 2024 (DHK-METRO-GA-11-2041) drove 184.2 km today between 08:15 AM and 04:30 PM.","data":[{"imei":"864540081293581","distance_km":184.2}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","example":"Which vehicle drove the most distance today?"}}},"example":{"prompt":"Which vehicle drove the most distance today?"}}}},"tags":["AI Assistant"],"summary":"Query Fleet Telematics via Natural Language AI Copilot","security":[{"bearerAuth":[]}]}},"/api/ai/presets":{"get":{"description":"Retrieves a paginated list of Ai Presets accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["AI Assistant"],"summary":"Get Ai Presets"}},"/api/ai/models":{"get":{"description":"Retrieves a paginated list of Ai Models accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["AI Assistant"],"summary":"Get Ai Models"}},"/api/ai/health":{"get":{"description":"Retrieves a paginated list of Ai Health accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["AI Assistant"],"summary":"Get Ai Health"}},"/api/certificates/generate":{"post":{"description":"Creates an official government/regulatory compliance certificate for a vehicle verifying that a certified AIS-140 / GPS tracker and emergency panic button are professionally installed.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Certificate generated with downloadable PDF URL."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imei"],"properties":{"imei":{"type":"string","example":"864540081293581"},"technician_name":{"type":"string","example":"Md. Kabir Hossain"},"certification_authority":{"type":"string","example":"BRTA Compliant VTS"}}},"example":{"imei":"864540081293581","technician_name":"Md. Kabir Hossain"}}}},"tags":["Certificates"],"summary":"Generate Official GPS Tracker Installation Certificate (PDF)","security":[{"bearerAuth":[]}]}},"/api/devices/{imei}/recordings":{"get":{"description":"Retrieves audio recordings and media uploaded from devices via 0x8D or HTTP upload.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"List of device recordings."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"List Audio / Video Recordings Uploaded for Device","security":[{"bearerAuth":[]}]}},"/api/recordings/{id}/download":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Recordings Id Download within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"Get Recordings Id Download"}},"/api/recordings/{id}":{"delete":{"description":"Permanently removes or unlinks the target Recordings Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"Delete Recordings Id"}},"/api/devices/{imei}/alarm-attachments":{"get":{"description":"Retrieves photo snapshots and video clips captured automatically during harsh braking, crash collision, driver distraction (DMS), or forward collision warning (FCW).","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"List of alarm attachments with presigned thumbnail and video URLs."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"List Dashcam Alarm Snapshots & Video Evidence","security":[{"bearerAuth":[]}]}},"/api/alarm-attachments/{id}/download":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Alarm-attachments Id Download within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"Get Alarm-attachments Id Download"}},"/api/alarm-attachments/{id}":{"delete":{"description":"Permanently removes or unlinks the target Alarm-attachments Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"Delete Alarm-attachments Id"}},"/api/video/health/summary":{"get":{"summary":"Get video health summary metrics","description":"Retrieves aggregate health counts: total cameras, recording ok, warnings, faults, offline.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/health":{"get":{"summary":"List video device health status","description":"Lists video-configured devices with SD card status, recording state, storage %, active alerts.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"fleet_id","in":"query","schema":{"type":"string","example":14},"description":"Fleet or subgroup numerical identifier"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/health/{imei}":{"get":{"summary":"Get single device video health","description":"Retrieves current video health and recent 50 audit log entries for a device.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/health/{imei}/acknowledge":{"post":{"summary":"Acknowledge video fault","description":"Marks an active video fault as acknowledged by a manager.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"example":"any"}}}}}},"tags":["Video Telematics"]}},"/api/video/health/{imei}/resolve":{"post":{"summary":"Resolve video fault","description":"Marks a video fault as resolved and resets recording status.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"example":"any"}}}}}},"tags":["Video Telematics"]}},"/api/video/health/{imei}/enable-snippets":{"post":{"summary":"Re-enable snippet capture","description":"Re-enables automated snippet capture for a device after consecutive failures.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/events/summary":{"get":{"summary":"Get event video inbox summary counts","description":"Retrieves total unreviewed, critical, high, reviewed, coached, and dismissed counts.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/events":{"get":{"summary":"Query Event Video Inbox","description":"Retrieves video event clips with filters by event_type, severity, review_status, imei, driver_id, dates.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"event_type","in":"query","schema":{"type":"string"}},{"name":"severity","in":"query","schema":{"type":"string"}},{"name":"review_status","in":"query","schema":{"type":"string"}},{"name":"imei","in":"query","schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"driver_id","in":"query","schema":{"type":"string"}},{"name":"date_from","in":"query","schema":{"type":"string"}},{"name":"date_to","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/events/{id}":{"get":{"summary":"Get single event video detail","description":"Retrieves event details, telemetry overlay, driver, and review information.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/events/{id}/review":{"patch":{"summary":"Review video event clip","description":"Updates review status (reviewed, coached, dismissed) and manager notes.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Video Telematics"]}},"/api/trailers":{"get":{"description":"Retrieves trailer chassis inventory with current hitching status and paired prime mover / tractor truck.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of trailers."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trailers"],"summary":"List Commercial Trailers & Detachable Assets","security":[{"bearerAuth":[]}]},"post":{"description":"Adds a new trailer chassis, flatbed, or reefer box to the fleet.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Trailer created."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"plate_number":{"example":"any"},"trailer_type":{"example":"any"},"rfid_tag":{"example":"any"},"ble_uuid":{"example":"any"},"cargo_capacity_kg":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Trailers"],"summary":"Register New Trailer Asset","security":[{"bearerAuth":[]}]}},"/api/trailers/{id}":{"put":{"description":"Updates and overwrites properties of the target Trailers Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"example":"any"},"plate_number":{"example":"any"},"trailer_type":{"example":"any"},"rfid_tag":{"example":"any"},"ble_uuid":{"example":"any"},"cargo_capacity_kg":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Trailers"],"summary":"Update Trailers Id"},"delete":{"description":"Permanently removes or unlinks the target Trailers Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trailers"],"summary":"Delete Trailers Id"}},"/api/trailers/{id}/hitch":{"post":{"description":"Provisions, dispatches, or creates a new Trailers Id Hitch in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_imei":{"example":"any"},"notes":{"example":"any"}}}}}},"tags":["Trailers"],"summary":"Create or Trigger Trailers Id Hitch"}},"/api/trailers/{id}/unhitch":{"post":{"description":"Provisions, dispatches, or creates a new Trailers Id Unhitch in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trailers"],"summary":"Create or Trigger Trailers Id Unhitch"}},"/api/trailers/{id}/history":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Trailers Id History within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trailers"],"summary":"Get Trailers Id History"}},"/api/video/{imei}/channels":{"get":{"summary":"Get Available Dashcam & Mobile DVR Camera Channels","description":"Retrieves logical and physical camera video channels for a mobile digital video recorder (MDVR/dashcam) complying with JT/T 1078 (e.g. Channel 1 = Road View / Forward ADAS, Channel 2 = Driver Cabin / DMS, Channel 3 = Cargo Bay, Channel 4 = Rear View).","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit dashcam IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of camera channels with stream formats.","content":{"application/json":{"example":{"success":true,"data":[{"channel":1,"name":"Forward Road (ADAS)","stream_type":0,"ptz_supported":false},{"channel":2,"name":"Driver In-Cabin (DMS)","stream_type":0,"ptz_supported":false}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"],"security":[{"bearerAuth":[]}]}},"/api/video/{imei}/properties":{"post":{"summary":"Query terminal A/V capabilities","description":"Sends a 0x9003 command to the terminal to query its A/V capabilities (response 0x1003).","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/capabilities":{"get":{"summary":"Fetch full device capabilities","description":"Retrieves device capabilities from the database.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]},"post":{"summary":"Override terminal A/V capabilities manually","description":"Updates terminal audio/video capabilities manually in the database.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/stream/check":{"post":{"summary":"Ping camera with a tiny real stream","description":"Performs a pre-flight check to verify if the camera can successfully establish a stream.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/stream/start":{"post":{"summary":"Start JT/T 1078 Live Real-Time Video Stream","description":"Sends a JT/T 1078 0x9101 instruction to the dashcam terminal to establish an active RTP/AV stream to the media gateway, returning WebSocket or HLS live video URL for playback in the dashboard.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit dashcam IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Live stream session established with player URL.","content":{"application/json":{"example":{"success":true,"data":{"sessionId":"stream-864540081293581-ch1","wsUrl":"wss://video.vegagps.com/live/864540081293581_1.flv","hlsUrl":"https://video.vegagps.com/live/864540081293581_1/index.m3u8","channel":1}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channel"],"properties":{"channel":{"type":"integer","description":"Logical camera channel number (1-8)","example":1},"dataType":{"type":"integer","description":"0 = Audio & Video, 1 = Video only, 2 = Audio only","default":0,"example":0},"streamType":{"type":"integer","description":"0 = Sub-stream (low bandwidth), 1 = Main-stream (HD)","default":0,"example":0}}},"example":{"channel":1,"dataType":0,"streamType":0}}}}}},"/api/video/{imei}/stream/stop":{"post":{"summary":"Stop Active Live Video Stream","description":"Sends a 0x9102 instruction to tear down the live RTP media session and conserve cellular data on the dashcam SIM.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit dashcam IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Stream session closed."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channel"],"properties":{"channel":{"type":"integer","example":1}}},"example":{"channel":1}}}}}},"/api/video/{imei}/stream/proxy":{"get":{"summary":"Proxy stream through ffmpeg","description":"Proxies the live stream (e.g., transcoding HEVC to H.264).","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/stream/control":{"post":{"summary":"Control active stream","description":"Send control commands (e.g., change quality, switch sub/main stream) to an active live stream.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/audio/monitor/start":{"post":{"summary":"Start audio-only stream","description":"Starts listening to the cabin audio monitor stream.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/audio/monitor/stop":{"post":{"summary":"Stop audio monitor stream","description":"Stops the cabin audio monitor stream.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/ptt/start":{"post":{"summary":"Begin PTT session","description":"Initiates a Push-to-Talk (PTT) session to speak to the driver. Returns a WebRTC push URL.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/ptt/stop":{"post":{"summary":"End PTT session","description":"Ends an active Push-to-Talk (PTT) session.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/recordings/query":{"post":{"summary":"Search Remote SD Card Video Recordings","description":"Sends a 0x9205 command to search local SD card video clips stored on the dashcam device within a specified time range.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit dashcam IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of video files stored on terminal SD card."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channel","startTime","endTime"],"properties":{"channel":{"type":"integer","example":1},"startTime":{"type":"string","example":"2026-10-01 08:00:00"},"endTime":{"type":"string","example":"2026-10-01 10:00:00"},"alarmType":{"type":"integer","description":"0 for all, or specific JT/T alarm bitmask","default":0,"example":0}}},"example":{"channel":1,"startTime":"2026-10-01 08:00:00","endTime":"2026-10-01 10:00:00"}}}}}},"/api/video/{imei}/recordings":{"get":{"summary":"Fetch recording lists","description":"Retrieves previously queried recording lists from the database.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/recordings/download":{"get":{"summary":"Download historical recording segment","description":"Triggers playback and downloads the specified historical segment as an MP4 file.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/recordings/play":{"post":{"summary":"Start playback","description":"Commands the device to stream a specific historical recording.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/recordings/control":{"post":{"summary":"Control playback","description":"Send playback control commands (pause, seek, speed up/down) for historical recordings.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/ptz":{"post":{"summary":"Pan/Tilt/Zoom Control","description":"Send PTZ commands (Pan/Tilt/Zoom/Focus/Iris/Wiper/Infrared) to a compatible camera.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/config":{"post":{"summary":"Set video/safety parameters","description":"Configure terminal video and safety parameters (0x0075-0x007C, 0xF364-0xF367).","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/snippets":{"post":{"summary":"Manually trigger video snippet capture","description":"Queues a manual on-demand video snippet capture job.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]},"get":{"summary":"List captured video snippets","description":"Retrieves a list of video snippets captured on alarm triggers for a device.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/snippets/quota":{"get":{"summary":"Get video snippet storage quota usage","description":"Retrieves the total storage usage of video snippets for a device versus its quota.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/snippets/{id}":{"get":{"summary":"Get video snippet details","description":"Retrieves the details and playback URL for a specific video snippet.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Snippet UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]},"delete":{"summary":"Delete a video snippet","description":"Deletes a video snippet file from storage and its metadata record from the database.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Snippet UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/video/{imei}/snippets/{id}/file":{"get":{"summary":"Stream video snippet MP4 file","description":"Streams a video snippet MP4 file with CORS and byte-range request support for browser video playback.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"Device IMEI"},{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Snippet UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Video Telematics"]}},"/api/jimi/internal/jimi/upload":{"post":{"description":"Provisions, dispatches, or creates a new Jimi Internal Jimi Upload in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imei":{"example":"any"},"filename":{"example":"any"},"fileName":{"example":"any"},"timestamp":{"example":"any"},"sign":{"example":"any"},"callbackBody":{"example":"any"},"fileType":{"example":"any"}}}}}},"tags":["Uploads & Media"],"summary":"Create or Trigger Jimi Internal Jimi Upload"}},"/api/jimi/upload":{"post":{"description":"Provisions, dispatches, or creates a new Jimi Upload in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"imei":{"example":"any"},"filename":{"example":"any"},"fileName":{"example":"any"},"timestamp":{"example":"any"},"sign":{"example":"any"},"callbackBody":{"example":"any"},"fileType":{"example":"any"}}}}}},"tags":["Uploads & Media"],"summary":"Create or Trigger Jimi Upload"}},"/api/jimi/jimi/{imei}/uploads":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Jimi Jimi Imei Uploads within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"imei","in":"path","required":true,"schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"page","in":"query","schema":{"type":"string","default":1,"example":1},"description":"Page number for pagination (starts at 1)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"Get Jimi Jimi Imei Uploads"}},"/api/jimi/jimi/uploads/{id}/download":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Jimi Jimi Uploads Id Download within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"Get Jimi Jimi Uploads Id Download"}},"/api/jimi/jimi/uploads/{id}":{"delete":{"description":"Permanently removes or unlinks the target Jimi Jimi Uploads Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Uploads & Media"],"summary":"Delete Jimi Jimi Uploads Id"}},"/api/trip-notes":{"get":{"description":"Retrieves a paginated list of Trip-notes accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"device_id","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","example":"2026-10-01T00:00:00Z"},"description":"Start timestamp (ISO-8601 UTC)"},{"name":"to","in":"query","schema":{"type":"string","example":"2026-10-01T23:59:59Z"},"description":"End timestamp (ISO-8601 UTC)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Notes"],"summary":"Get Trip-notes"},"post":{"description":"Provisions, dispatches, or creates a new Trip-notes in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_imei":{"example":"any"},"trip_start":{"example":"any"},"trip_end":{"example":"any"},"label":{"example":"any"},"category":{"example":"any"},"note":{"example":"any"}}}}}},"tags":["Trip Notes"],"summary":"Create or Trigger Trip-notes"}},"/api/trip-notes/{id}":{"put":{"description":"Updates and overwrites properties of the target Trip-notes Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"example":"any"},"category":{"example":"any"},"note":{"example":"any"}}}}}},"tags":["Trip Notes"],"summary":"Update Trip-notes Id"},"delete":{"description":"Permanently removes or unlinks the target Trip-notes Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Notes"],"summary":"Delete Trip-notes Id"}},"/api/trips/templates":{"get":{"description":"Retrieves predefined commercial trip route templates (e.g. Factory-to-Port, Depot-to-Store) including planned stops, geofences, baseline transit durations, and fuel budgets.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"trip_type","in":"query","schema":{"type":"string"}},{"name":"is_active","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of configured trip templates.","content":{"application/json":{"example":{"success":true,"data":[{"id":"tmpl-dhk-ctg","name":"Dhaka to Chittagong Port Cargo Corridor","trip_type":"FR-RT","origin":"Tejgaon Industrial Area","destination":"Chittagong Port Yard 4","planned_distance_km":245,"estimated_hours":6.5,"fuel_budget_liters":75}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"List Master Trip Route Templates","security":[{"bearerAuth":[]}]},"post":{"description":"Defines a new standardized commercial trip blueprint with planned origin, destination, intermediate checkpoints, and cargo specifications.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Trip template created."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Create Master Trip Template","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","origin","destination"],"properties":{"name":{"type":"string","example":"Dhaka to Sylhet Express"},"origin":{"type":"string","example":"Dhaka Central Hub"},"destination":{"type":"string","example":"Sylhet Regional Depot"},"planned_distance_km":{"type":"number","example":240},"fuel_budget_liters":{"type":"number","example":65}}},"example":{"name":"Dhaka to Sylhet Express","origin":"Dhaka Central Hub","destination":"Sylhet Regional Depot","planned_distance_km":240,"fuel_budget_liters":65}}}}}},"/api/trips/templates/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Trips Templates Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Get Trips Templates Id"},"delete":{"description":"Permanently removes or unlinks the target Trips Templates Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Delete Trips Templates Id"}},"/api/trips/active":{"get":{"description":"Retrieves all vehicles currently on an active route, including transit progress, live ETA, route deviation status, and current driver.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"List of active dispatches in progress."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Get All Currently Active Dispatched Fleet Trips","security":[{"bearerAuth":[]}]}},"/api/trips/instances/active":{"get":{"description":"Retrieves a paginated list of Trips Instances Active accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Get Trips Instances Active"}},"/api/trips/instances":{"get":{"description":"Retrieves a paginated list of Trips Instances accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"},{"name":"imei","in":"query","schema":{"type":"string","example":"864540081293581"},"description":"15-digit unique hardware IMEI number"},{"name":"trip_type","in":"query","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string"}},{"name":"end_date","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"offset","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Get Trips Instances"}},"/api/trips/instances/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Trips Instances Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Get Trips Instances Id"}},"/api/trips/instances/{id}/report":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Trips Instances Id Report within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Get Trips Instances Id Report"}},"/api/trips/instances/{id}/fuel-curve":{"get":{"description":"Calculates fuel burn efficiency across trip legs, correlating gradient changes, speed, vehicle load, and refuel events against distance travelled.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"trip-2026-10-001"},"description":"Trip instance ID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"Correlated fuel vs distance points and consumption rate (KPL)."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Get Fuel Consumption vs Distance Telemetry Curve for Trip","security":[{"bearerAuth":[]}]}},"/api/trips/dispatch":{"post":{"description":"Initiates an active commercial dispatch for a vehicle, assigning driver, cargo manifest, trailer, and origin/destination checkpoints. Starts real-time compliance tracking.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Trip dispatched successfully."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Dispatch New Vehicle Trip Instance","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_imei","origin","destination"],"properties":{"device_imei":{"type":"string","example":"864540081293581"},"template_id":{"type":"string","example":"tmpl-dhk-ctg"},"driver_id":{"type":"string","example":"drv-01"},"origin":{"type":"string","example":"Tejgaon Logistics Center"},"destination":{"type":"string","example":"Chittagong Port"},"cargo_weight_kg":{"type":"number","example":12500},"revenue_amount":{"type":"number","example":35000}}},"example":{"device_imei":"864540081293581","driver_id":"drv-01","origin":"Tejgaon Logistics Center","destination":"Chittagong Port","cargo_weight_kg":12500}}}}}},"/api/trips/instances/{id}/status":{"patch":{"description":"Applies partial field modifications to the target Trips Instances Id Status.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Trip Engine"],"summary":"Modify Trips Instances Id Status"}},"/api/trips/instances/{id}/financials":{"patch":{"description":"Applies partial field modifications to the target Trips Instances Id Financials.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cargo_description":{"example":"any"},"cargo_weight_kg":{"example":"any"},"cargo_type":{"example":"any"},"revenue_amount":{"example":"any"},"revenue_currency":{"example":"any"},"fuel_expense_cost":{"example":"any"},"toll_expenses":{"example":"any"},"driver_allowance":{"example":"any"},"border_clearance_fees":{"example":"any"},"other_expenses":{"example":"any"}}}}}},"tags":["Trip Engine"],"summary":"Modify Trips Instances Id Financials"}},"/api/search":{"get":{"description":"Performs lightning-fast substring search across vehicle plates, names, device IMEIs, assigned drivers, and geofence locations in one query.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"q","in":"query","schema":{"type":"string","example":"Allion"},"required":true,"description":"Search keyword (plate, IMEI, driver name, vehicle model)"},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"Categorized search results.","content":{"application/json":{"example":{"success":true,"data":{"devices":[{"imei":"864540081293581","name":"Toyota Allion 2024","plate_number":"DHK-11-2041"}],"drivers":[],"geofences":[]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Search"],"summary":"Unified Global Search Across Entire Fleet","security":[{"bearerAuth":[]}]}},"/api/elocks":{"get":{"description":"Retrieves a paginated list of Elocks accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks"},"post":{"description":"Provisions, dispatches, or creates a new Elocks in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Create or Trigger Elocks"}},"/api/elocks/stats":{"get":{"description":"Retrieves a paginated list of Elocks Stats accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Stats"}},"/api/elocks/settings":{"get":{"description":"Retrieves a paginated list of Elocks Settings accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Settings"},"put":{"description":"Updates and overwrites properties of the target Elocks Settings.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Update Elocks Settings"}},"/api/elocks/tamper-events":{"get":{"description":"Retrieves a paginated list of Elocks Tamper-events accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"event_type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Tamper-events"}},"/api/elocks/alerts":{"get":{"description":"Retrieves a paginated list of Elocks Alerts accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"event_type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Alerts"}},"/api/elocks/inspections":{"get":{"description":"Retrieves a paginated list of Elocks Inspections accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Inspections"}},"/api/elocks/corridors":{"get":{"description":"Retrieves a paginated list of Elocks Corridors accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Corridors"}},"/api/elocks/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Elocks Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Id"},"put":{"description":"Updates and overwrites properties of the target Elocks Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Update Elocks Id"},"patch":{"description":"Applies partial field modifications to the target Elocks Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Modify Elocks Id"},"delete":{"description":"Permanently removes or unlinks the target Elocks Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Delete Elocks Id"}},"/api/elocks/{id}/readiness":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Elocks Id Readiness within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Id Readiness"}},"/api/elocks/{id}/dispatch":{"post":{"description":"Provisions, dispatches, or creates a new Elocks Id Dispatch in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Create or Trigger Elocks Id Dispatch"}},"/api/elocks/{id}/inspection":{"post":{"description":"Provisions, dispatches, or creates a new Elocks Id Inspection in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Create or Trigger Elocks Id Inspection"}},"/api/elocks/{id}/tamper-events":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Elocks Id Tamper-events within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"},{"name":"event_type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Id Tamper-events"}},"/api/elocks/{id}/inspections":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Elocks Id Inspections within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"limit","in":"query","schema":{"type":"string","default":50,"example":25},"description":"Number of records per page (max 1000)"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Elocks Id Inspections"}},"/api/coldchain/profiles":{"get":{"description":"Retrieves a paginated list of Coldchain Profiles accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"is_active","in":"query","schema":{"type":"string"}},{"name":"cargo_type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Coldchain Profiles"},"post":{"description":"Provisions, dispatches, or creates a new Coldchain Profiles in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Create or Trigger Coldchain Profiles"}},"/api/coldchain/profiles/{id}":{"get":{"description":"Retrieves detailed properties, configuration, and telemetry state for a specific Coldchain Profiles Id within the caller's organization hierarchy.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Coldchain Profiles Id"},"put":{"description":"Updates and overwrites properties of the target Coldchain Profiles Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Update Coldchain Profiles Id"},"delete":{"description":"Permanently removes or unlinks the target Coldchain Profiles Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Delete Coldchain Profiles Id"}},"/api/coldchain/rate-cards":{"get":{"description":"Retrieves a paginated list of Coldchain Rate-cards accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"make","in":"query","schema":{"type":"string"}},{"name":"is_active","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Coldchain Rate-cards"},"post":{"description":"Provisions, dispatches, or creates a new Coldchain Rate-cards in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Create or Trigger Coldchain Rate-cards"}},"/api/coldchain/rate-cards/{id}":{"put":{"description":"Updates and overwrites properties of the target Coldchain Rate-cards Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Update Coldchain Rate-cards Id"},"delete":{"description":"Permanently removes or unlinks the target Coldchain Rate-cards Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Delete Coldchain Rate-cards Id"}},"/api/coldchain/pairings":{"get":{"description":"Retrieves a paginated list of Coldchain Pairings accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""},{"name":"is_active","in":"query","schema":{"type":"string"}},{"name":"origin_geofence_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Coldchain Pairings"},"post":{"description":"Provisions, dispatches, or creates a new Coldchain Pairings in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Create or Trigger Coldchain Pairings"}},"/api/coldchain/pairings/{id}":{"put":{"description":"Updates and overwrites properties of the target Coldchain Pairings Id.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Update Coldchain Pairings Id"},"delete":{"description":"Permanently removes or unlinks the target Coldchain Pairings Id from the organization inventory.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"},{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Delete Coldchain Pairings Id"}},"/api/coldchain/scoring-weights":{"get":{"description":"Retrieves a paginated list of Coldchain Scoring-weights accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Get Coldchain Scoring-weights"},"put":{"description":"Updates and overwrites properties of the target Coldchain Scoring-weights.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["my","child","all"],"example":"my"},"description":"Tenant organization hierarchy scope: \"my\" (current org only), \"child\" (sub-accounts), or \"all\""}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["default"],"summary":"Update Coldchain Scoring-weights"}},"/auth/register":{"post":{"description":"Provisions a new tenant organization and its initial administrator account.\n\n### Use Case\nSelf-service onboarding flow for new fleet customers. Automatically generates a unique tenant slug, initializes organization billing quotas, sets up default roles, and signs the user in.","responses":{"201":{"description":"Registration successful. Organization and user provisioned.","content":{"application/json":{"example":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","user":{"id":"d8e411fa-51a2-47d0-8f92-9118e47851ad","name":"Kariuki Kamau","email":"admin@safari-express.co.ke","role":"admin","org_id":"1e5e01b1-2182-4f05-b072-a7d0e1948831","org_name":"Safari Express Freight Ltd"}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"409":{"description":"Conflict: user with this email address already exists.","content":{"application/json":{"example":{"error":"User already exists"}}}},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"parameters":[],"summary":"Register New Organization & Admin Account","requestBody":{"required":true,"description":"New account and organization registration details","content":{"application/json":{"schema":{"type":"object","required":["name","email","password","orgName"],"properties":{"name":{"type":"string","description":"Full name of the primary administrator","example":"Kariuki Kamau"},"email":{"type":"string","format":"email","description":"Corporate email address for login and notifications","example":"admin@safari-express.co.ke"},"password":{"type":"string","format":"password","minLength":4,"maxLength":10,"description":"Account password (4 to 10 characters)","example":"Pass1234"},"orgName":{"type":"string","description":"Company or fleet organization legal name","example":"Safari Express Freight Ltd"}}},"example":{"name":"Kariuki Kamau","email":"admin@safari-express.co.ke","password":"Pass1234","orgName":"Safari Express Freight Ltd"}}}}}},"/auth/login":{"post":{"description":"Authenticates a user using their email, username, or phone number along with their password.\n\n### Use Case\nThis is the primary authentication entrypoint for web dashboards, mobile apps, and third-party API clients interacting with the Platform REST API (`/api/*`). Upon successful verification, the service issues a cryptographically signed JWT bearer token that must be supplied in subsequent requests.\n\n### Multi-Identifier Login\nThe `email` field accepts any of the following:\n- Registered email address (e.g. `ops@company.com`)\n- Phone number (e.g. `+8801712345678`)\n- Username (e.g. `dispatcher1`)","responses":{"200":{"description":"Login successful. Returns JWT access token and user profile context.","content":{"application/json":{"example":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJjMWY3Yjc2ZS0zNDdmLTQ0ZGUtOWU1Yy0wYzE1M2I2NjRkNGIiLCJvcmdJZCI6IjkwZTU0NGNlLWQyODQtNDhmMC1iOGQ0LTYzZmNiMDAxYTFjNSIsImlhdCI6MTc5MDg1MDIwMCwiZXhwIjoxNzkzNDQyMjAwfQ.Signature","user":{"id":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","name":"Fleet Dispatcher","email":"dispatcher@xeekar.com","role":"dispatcher","org_id":"90e544ce-d284-48f0-b8d4-63fcb001a1c5","org_name":"Xeekar Logistics","timezone":"Asia/Dhaka","is_platform_admin":false}}}}},"400":{"description":"Validation error: missing required fields or invalid format.","content":{"application/json":{"example":{"error":[{"code":"invalid_type","expected":"string","received":"undefined","path":["email"],"message":"Required"},{"code":"invalid_type","expected":"string","received":"undefined","path":["password"],"message":"Required"}]}}}},"401":{"description":"Authentication failure: invalid email/password combination.","content":{"application/json":{"example":{"error":"Invalid credentials"}}}},"403":{"description":"Account or Organization deactivated.","content":{"application/json":{"example":{"success":false,"error":"Your account has been temporarily deactivated. Please contact your administrator.","code":"ACCOUNT_DEACTIVATED"}}}},"429":{"description":"Rate limit exceeded: too many failed attempts (50 attempts per 10 minutes).","content":{"application/json":{"example":{"error":"Too many login attempts, please try again later."}}}},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"parameters":[],"summary":"Authenticate User & Obtain JWT Access Token","requestBody":{"required":true,"description":"User login credentials and session options","content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","description":"Registered user email, username, or phone number","example":"dispatcher@xeekar.com"},"password":{"type":"string","format":"password","description":"Account password","example":"SuperSecretPass123!"},"rememberMe":{"type":"boolean","description":"Extend token validity duration from standard (30 days) to persistent (90 days)","default":false,"example":true}}},"example":{"email":"dispatcher@xeekar.com","password":"SuperSecretPass123!","rememberMe":true}}}}}},"/auth/request-access":{"post":{"description":"Provisions, dispatches, or creates a new Auth Request-access in the organization, validating request parameters and verifying tenant access permissions.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"409":{"description":"Conflict"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"parameters":[],"summary":"Create or Trigger Auth Request-access"}},"/auth/signup-requests":{"get":{"description":"Retrieves a paginated list of Auth Signup-requests accessible to the user's tenant organization scope, with support for filtering and search queries.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"status","in":"query","schema":{"type":"string","example":"active"},"description":"Filter by operational status"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"summary":"Get Auth Signup-requests"}},"/auth/signup-requests/{id}/approve":{"patch":{"description":"Applies partial field modifications to the target Auth Signup-requests Id Approve.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"summary":"Modify Auth Signup-requests Id Approve"}},"/auth/signup-requests/{id}/reject":{"patch":{"description":"Applies partial field modifications to the target Auth Signup-requests Id Reject.\n\n### Authorization & Security\nProtected endpoint. Pass a valid JWT Bearer token in the `Authorization` header (`Bearer `) or organization API key. Resource access is strictly gated by the caller's assigned tenant scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"14"},"description":"Unique resource identifier or UUID"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"example":"any"}}}}}},"tags":["Authentication"],"summary":"Modify Auth Signup-requests Id Reject"}},"/auth/forgot-password":{"post":{"description":"Sends a cryptographically secure, time-limited password reset link to the user's verified email address.\n\n### Use Case\nUser self-service recovery when credentials are lost. Rate-limited to prevent abuse.","responses":{"200":{"description":"Reset request received. An email is dispatched if the user exists.","content":{"application/json":{"example":{"success":true,"message":"Password reset link sent to your email."}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"parameters":[],"summary":"Request Password Reset Email Link","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Registered user email address","example":"user@company.com"}}},"example":{"email":"user@company.com"}}}}}},"/auth/reset-password":{"post":{"description":"Completes the password reset process using the secure token received via email.","responses":{"200":{"description":"Password successfully updated. All previous sessions invalidated.","content":{"application/json":{"example":{"success":true,"message":"Password has been reset successfully."}}}},"400":{"description":"Invalid or expired reset token."},"401":{"description":"Unauthorized — missing or invalid credentials"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"parameters":[],"summary":"Reset Password Using Token","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","newPassword"],"properties":{"token":{"type":"string","description":"Reset token from the email link query string","example":"9fa82b5d4e1c..."},"newPassword":{"type":"string","format":"password","description":"New secure password (min 8 characters)","example":"NewSecurePass2026!"}}},"example":{"token":"9fa82b5d4e1c...","newPassword":"NewSecurePass2026!"}}}}}},"/auth/logout":{"post":{"description":"Invalidates the current session token in Redis and server session registry.\n\n### Use Case\nEnsures secure sign-out. After calling this endpoint, the token cannot be used again even if it has not yet expired.","parameters":[],"responses":{"200":{"description":"Logged out successfully.","content":{"application/json":{"example":{"success":true,"message":"Logged out successfully"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"summary":"Terminate Active Session & Revoke Token","security":[{"bearerAuth":[]}]}},"/auth/change-password":{"put":{"description":"Allows an authenticated user to change their account password by verifying their current password.","parameters":[],"responses":{"200":{"description":"Password changed successfully."},"400":{"description":"Bad Request"},"401":{"description":"Incorrect current password."},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"summary":"Change Password for Authenticated User","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["currentPassword","newPassword"],"properties":{"currentPassword":{"type":"string","format":"password","description":"Current valid password","example":"CurrentPass123!"},"newPassword":{"type":"string","format":"password","description":"New secure password (min 8 characters)","example":"UpdatedSecurePass456!"}}},"example":{"currentPassword":"CurrentPass123!","newPassword":"UpdatedSecurePass456!"}}}}}},"/auth/me":{"get":{"description":"Retrieves the full profile, active session context, organization details, and permissions of the currently authenticated token.\n\n### Use Case\nUsed during application bootstrap and page refreshes to verify token validity, fetch permissions for UI feature flags, and hydrate active organization state.","parameters":[],"responses":{"200":{"description":"Current user profile context.","content":{"application/json":{"example":{"user":{"id":"c1f7b76e-347f-44de-9e5c-0c153b664d4b","name":"Fleet Dispatcher","email":"dispatcher@xeekar.com","role":"dispatcher","org_id":"90e544ce-d284-48f0-b8d4-63fcb001a1c5","org_name":"Xeekar Logistics","timezone":"Asia/Dhaka","is_platform_admin":false,"permissions":["devices:view","devices:edit","tracking:live","reports:generate","commands:send"]}}}}},"401":{"description":"Unauthorized: missing, expired, or corrupted Bearer JWT token."},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"},"503":{"description":"Service Unavailable"}},"tags":["Authentication"],"summary":"Get Current Authenticated User Profile & Permissions","security":[{"bearerAuth":[]}]}},"/auth/sessions":{"get":{"description":"Returns active sessions associated with the current user, including client IP, device model, user-agent, and login timestamp.","parameters":[],"responses":{"200":{"description":"List of active sessions.","content":{"application/json":{"example":{"sessions":[{"id":"sess_91b72e","ip":"103.205.134.12","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)","device_name":"Chrome on macOS","current":true,"created_at":"2026-10-01T08:30:00Z"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"summary":"List All Active User Sessions","security":[{"bearerAuth":[]}]}},"/auth/sessions/{sessionId}":{"delete":{"description":"Terminates a specific remote session by session ID.","parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","example":"sess_91b72e"},"description":"Session identifier to terminate"}],"responses":{"200":{"description":"Session successfully revoked."},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — insufficient RBAC permissions or target resource outside data scope"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}},"tags":["Authentication"],"summary":"Revoke Specific User Session","security":[{"bearerAuth":[]}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"JWT Bearer token. Format: `Bearer `"},"apiKeyAuth":{"type":"apiKey","in":"query","name":"api_key","description":"Organization API Key for V1 Public Integration endpoints"}}},"security":[{"bearerAuth":[]}]}}