{"components":{"schemas":{"AggregateRefresh":{"properties":{"coverageFrom":{"format":"date-time","nullable":true,"type":"string"},"coverageTo":{"format":"date-time","nullable":true,"type":"string"},"status":{"description":"Latest refresh status.","type":"string"},"updatedAt":{"format":"date-time","nullable":true,"type":"string"}},"type":"object"},"AssetRef":{"properties":{"assetType":{"description":"Asset type name.","type":"string"},"customerName":{"description":"Customer name assigned to the asset. Customer-scoped API keys are restricted to rows whose customerName exactly matches the key scope.","type":"string"},"displayCode":{"description":"Human-readable display code.","type":"string"},"id":{"format":"uuid","type":"string"},"identifier":{"description":"Tenant asset identifier.","type":"string"},"location":{"description":"Location text.","type":"string"},"name":{"description":"Asset name.","type":"string"}},"type":"object"},"CancelResponse":{"properties":{"cancelled":{"type":"boolean"},"id":{"format":"uuid","type":"string"}},"type":"object"},"ContainerWorkSummary":{"description":"Container crane / reach stacker load-state metrics. adcin=on means the spreader is locked or a container/load is engaged; adcin=off means open or empty travel.","properties":{"containerCycleCount":{"type":"integer"},"emptyDistanceM":{"type":"number"},"emptySeconds":{"type":"integer"},"loadedDistanceM":{"type":"number"},"loadedPercent":{"type":"number"},"loadedSeconds":{"type":"integer"}},"type":"object"},"CountBreakdownItem":{"properties":{"count":{"type":"integer"},"label":{"description":"Breakdown label.","type":"string"}},"type":"object"},"DeleteResponse":{"properties":{"deleted":{"type":"boolean"},"id":{"format":"uuid","type":"string"}},"type":"object"},"ErrorResponse":{"properties":{"error":{"example":"invalid api key","type":"string"}},"required":["error"],"type":"object"},"ExternalApiKeyScope":{"properties":{"customerName":{"nullable":true,"type":"string"},"customerScoped":{"type":"boolean"},"name":{"description":"Configured key name.","type":"string"}},"type":"object"},"FileUploadRequest":{"properties":{"file":{"format":"binary","type":"string"}},"required":["file"],"type":"object"},"FileUploadResponse":{"properties":{"filename":{"description":"Stored filename.","type":"string"},"id":{"format":"uuid","type":"string"},"mimeType":{"description":"MIME type.","type":"string"},"sizeBytes":{"type":"integer"}},"type":"object"},"GeoJSONGeometry":{"description":"GeoJSON geometry object as defined by RFC 7946. Coordinates shape depends on the geometry type.","properties":{"bbox":{"items":{"type":"number"},"type":"array"},"coordinates":{"description":"GeoJSON coordinates array. Longitude comes before latitude. Nested array depth depends on geometry type.","items":{},"type":"array"},"type":{"enum":["Point","MultiPoint","LineString","MultiLineString","Polygon","MultiPolygon"],"type":"string"}},"required":["type","coordinates"],"type":"object"},"IDResponse":{"properties":{"id":{"format":"uuid","type":"string"}},"type":"object"},"MeResponse":{"properties":{"apiKey":{"$ref":"#/components/schemas/ExternalApiKeyScope"},"tenant":{"properties":{"id":{"format":"uuid","type":"string"},"name":{"description":"Tenant name.","type":"string"}},"type":"object"},"version":{"example":"external-v1","type":"string"}},"required":["tenant","apiKey","version"],"type":"object"},"OpenAPIObject":{"additionalProperties":true,"type":"object"},"Paging":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["limit","offset"],"type":"object"},"ReportingAsset":{"properties":{"assetType":{"description":"Asset type.","type":"string"},"createdAt":{"format":"date-time","nullable":true,"type":"string"},"customerEmail":{"description":"Customer email.","type":"string"},"customerName":{"description":"Customer name.","type":"string"},"customerPhone":{"description":"Customer phone.","type":"string"},"id":{"format":"uuid","type":"string"},"identifier":{"description":"Identifier.","type":"string"},"inspectionCount":{"type":"integer"},"latestImpact":{"description":"Latest report impact.","type":"string"},"latestInspectionAt":{"format":"date-time","nullable":true,"type":"string"},"latestOutcome":{"description":"Latest report outcome.","type":"string"},"latestReportAt":{"format":"date-time","nullable":true,"type":"string"},"lifecycleStatus":{"description":"Lifecycle status.","type":"string"},"location":{"description":"Location.","type":"string"},"name":{"description":"Asset name.","type":"string"},"operationalStatus":{"description":"Operational status.","type":"string"},"reportCount":{"type":"integer"},"status":{"description":"Operational status.","type":"string"},"updatedAt":{"format":"date-time","nullable":true,"type":"string"}},"type":"object"},"ReportingAssetListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ReportingAsset"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"},"scope":{"$ref":"#/components/schemas/Scope"}},"type":"object"},"ReportingAssetType":{"properties":{"assetCount":{"type":"integer"},"createdAt":{"format":"date-time","nullable":true,"type":"string"},"description":{"description":"Description.","type":"string"},"fields":{"additionalProperties":true,"type":"object"},"id":{"format":"uuid","type":"string"},"name":{"description":"Asset type name.","type":"string"},"updatedAt":{"format":"date-time","nullable":true,"type":"string"}},"type":"object"},"ReportingAssetTypeListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ReportingAssetType"},"type":"array"}},"type":"object"},"ReportingBreakdowns":{"properties":{"assetType":{"items":{"$ref":"#/components/schemas/CountBreakdownItem"},"type":"array"},"customer":{"items":{"$ref":"#/components/schemas/CountBreakdownItem"},"type":"array"},"inspectionStatus":{"items":{"$ref":"#/components/schemas/CountBreakdownItem"},"type":"array"},"location":{"items":{"$ref":"#/components/schemas/CountBreakdownItem"},"type":"array"},"reportOutcome":{"items":{"$ref":"#/components/schemas/CountBreakdownItem"},"type":"array"},"serviceRequestCancellationReason":{"items":{"$ref":"#/components/schemas/CountBreakdownItem"},"type":"array"},"serviceRequestCategory":{"items":{"$ref":"#/components/schemas/CountBreakdownItem"},"type":"array"},"serviceRequestPriority":{"items":{"$ref":"#/components/schemas/CountBreakdownItem"},"type":"array"},"serviceRequestStatus":{"items":{"$ref":"#/components/schemas/CountBreakdownItem"},"type":"array"},"template":{"items":{"$ref":"#/components/schemas/CountBreakdownItem"},"type":"array"}},"type":"object"},"ReportingInspection":{"properties":{"asset":{"$ref":"#/components/schemas/AssetRef"},"completedAt":{"format":"date-time","nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"media":{"additionalProperties":true,"type":"object"},"report":{"additionalProperties":true,"type":"object"},"startedAt":{"format":"date-time","nullable":true,"type":"string"},"status":{"description":"Inspection status.","type":"string"},"template":{"additionalProperties":true,"type":"object"}},"type":"object"},"ReportingInspectionListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ReportingInspection"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"},"range":{"$ref":"#/components/schemas/TimeRange"},"scope":{"$ref":"#/components/schemas/Scope"}},"type":"object"},"ReportingMonthlyMetric":{"properties":{"inspections":{"type":"integer"},"month":{"description":"YYYY-MM","type":"string"},"outOfService":{"type":"integer"},"rejected":{"type":"integer"},"reports":{"type":"integer"}},"type":"object"},"ReportingOverviewResponse":{"properties":{"apiKey":{"$ref":"#/components/schemas/ExternalApiKeyScope"},"breakdowns":{"$ref":"#/components/schemas/ReportingBreakdowns"},"monthly":{"items":{"$ref":"#/components/schemas/ReportingMonthlyMetric"},"type":"array"},"range":{"$ref":"#/components/schemas/TimeRange"},"recentReports":{"items":{"$ref":"#/components/schemas/ReportingRecentReport"},"type":"array"},"recentServiceRequests":{"items":{"$ref":"#/components/schemas/ServiceRequest"},"type":"array"},"scope":{"$ref":"#/components/schemas/Scope"},"summary":{"description":"Counters for assets, inspections, reports, media, customer links and service requests.","properties":{"activeAssets":{"type":"integer"},"assets":{"type":"integer"},"cancelledServiceRequests":{"type":"integer"},"closedServiceRequests":{"type":"integer"},"completedInspections":{"type":"integer"},"inactiveAssets":{"type":"integer"},"inspections":{"type":"integer"},"openServiceRequests":{"type":"integer"},"outOfServiceReports":{"type":"integer"},"rejectedInspections":{"type":"integer"},"rejectedReports":{"type":"integer"},"reports":{"type":"integer"},"resolvedServiceRequests":{"type":"integer"},"serviceCancellationRate":{"type":"number"},"serviceRequests":{"type":"integer"},"urgentServiceRequests":{"type":"integer"},"warningReports":{"type":"integer"}},"type":"object"}},"type":"object"},"ReportingRecentReport":{"properties":{"assetName":{"description":"Asset name.","type":"string"},"createdAt":{"format":"date-time","nullable":true,"type":"string"},"customerName":{"description":"Customer name.","type":"string"},"impact":{"description":"Impact.","type":"string"},"inspectionId":{"format":"uuid","type":"string"},"location":{"description":"Location.","type":"string"},"outcome":{"description":"Report outcome.","type":"string"},"rejectionReason":{"description":"Reason when rejected.","type":"string"},"reportId":{"format":"uuid","type":"string"},"templateName":{"description":"Inspection template.","type":"string"}},"type":"object"},"ReportingReport":{"properties":{"asset":{"$ref":"#/components/schemas/AssetRef"},"createdAt":{"format":"date-time","nullable":true,"type":"string"},"id":{"format":"uuid","type":"string"},"impact":{"description":"Impact.","type":"string"},"inspectionId":{"format":"uuid","type":"string"},"media":{"additionalProperties":true,"type":"object"},"outcome":{"description":"Report outcome.","type":"string"},"rejectionReason":{"description":"Rejection reason.","type":"string"},"template":{"additionalProperties":true,"type":"object"}},"type":"object"},"ReportingReportListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ReportingReport"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"},"range":{"$ref":"#/components/schemas/TimeRange"},"scope":{"$ref":"#/components/schemas/Scope"}},"type":"object"},"ReportingTemplate":{"properties":{"assetTypeIds":{"items":{"format":"uuid","type":"string"},"type":"array"},"createdAt":{"format":"date-time","nullable":true,"type":"string"},"description":{"description":"Description.","type":"string"},"id":{"format":"uuid","type":"string"},"latestVersion":{"type":"integer"},"name":{"description":"Template name.","type":"string"},"status":{"description":"Template status.","type":"string"},"updatedAt":{"format":"date-time","nullable":true,"type":"string"}},"type":"object"},"ReportingTemplateListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ReportingTemplate"},"type":"array"}},"type":"object"},"Scope":{"properties":{"customerName":{"nullable":true,"type":"string"},"customerScoped":{"type":"boolean"}},"type":"object"},"ServiceRequest":{"properties":{"asset":{"$ref":"#/components/schemas/AssetRef"},"assetId":{"format":"uuid","nullable":true,"type":"string"},"assignedTo":{"additionalProperties":true,"type":"object"},"assignedToUserId":{"format":"uuid","nullable":true,"type":"string"},"category":{"enum":["defect","maintenance_request","safety","cleaning","access","other"],"type":"string"},"closedAt":{"format":"date-time","nullable":true,"type":"string"},"createdAt":{"format":"date-time","nullable":true,"type":"string"},"customerEmail":{"description":"Customer email.","type":"string"},"customerName":{"description":"Customer name.","type":"string"},"customerPhone":{"description":"Customer phone.","type":"string"},"description":{"description":"Description.","type":"string"},"displayCode":{"description":"Human-readable service request code.","type":"string"},"dueAt":{"format":"date-time","nullable":true,"type":"string"},"externalRef":{"description":"External system reference.","type":"string"},"files":{"items":{"$ref":"#/components/schemas/ServiceRequestFile"},"type":"array"},"history":{"items":{"$ref":"#/components/schemas/ServiceRequestEvent"},"type":"array"},"id":{"format":"uuid","type":"string"},"location":{"description":"Location.","type":"string"},"metadata":{"additionalProperties":true,"type":"object"},"priority":{"enum":["low","normal","high","urgent"],"type":"string"},"reportedByEmail":{"description":"Reporter email.","type":"string"},"reportedByName":{"description":"Reporter name.","type":"string"},"resolution":{"description":"Resolution text.","type":"string"},"resolvedAt":{"format":"date-time","nullable":true,"type":"string"},"source":{"description":"internal, external, customer or widget.","type":"string"},"status":{"enum":["new","reopened","triaged","in_progress","waiting_customer","resolved","closed","cancelled"],"type":"string"},"title":{"description":"Title.","type":"string"},"updatedAt":{"format":"date-time","nullable":true,"type":"string"}},"type":"object"},"ServiceRequestCancelRequest":{"properties":{"duplicateOf":{"description":"Optional reference to another request.","type":"string"},"reason":{"description":"Required cancellation reason.","type":"string"}},"required":["reason"],"type":"object"},"ServiceRequestCreateRequest":{"example":{"category":"defect","customerName":"Kiinteistö Oy Esimerkki","description":"Vuoto näkyy altaan alla.","externalRef":"customer-portal-12345","priority":"high","reportedByEmail":"matti@example.com","title":"WC-hana vuotaa"},"properties":{"assetId":{"format":"uuid","nullable":true,"type":"string"},"category":{"default":"other","enum":["defect","maintenance_request","safety","cleaning","access","other"],"type":"string"},"comment":{"description":"Initial history comment.","type":"string"},"customerEmail":{"description":"Customer contact email.","type":"string"},"customerName":{"description":"Customer name. For customer-scoped keys this defaults to the key scope.","type":"string"},"customerPhone":{"description":"Customer contact phone.","type":"string"},"description":{"description":"Free-text description.","type":"string"},"dueAt":{"description":"YYYY-MM-DD or RFC3339.","type":"string"},"externalRef":{"description":"External system id for idempotent matching on client side.","type":"string"},"location":{"description":"Location.","type":"string"},"metadata":{"additionalProperties":true,"type":"object"},"priority":{"default":"normal","enum":["low","normal","high","urgent"],"type":"string"},"reportedByEmail":{"description":"Reporter email.","type":"string"},"reportedByName":{"description":"Reporter name.","type":"string"},"resolution":{"description":"Required when creating directly as resolved/closed.","type":"string"},"resolutionReviewed":{"type":"boolean"},"status":{"enum":["new","reopened","triaged","in_progress","waiting_customer","resolved","closed","cancelled"],"type":"string"},"title":{"description":"Required short title.","type":"string"}},"required":["title"],"type":"object"},"ServiceRequestEvent":{"properties":{"actorEmail":{"description":"Actor email.","type":"string"},"actorName":{"description":"Actor name.","type":"string"},"createdAt":{"format":"date-time","nullable":true,"type":"string"},"fromStatus":{"description":"Previous status.","type":"string"},"id":{"format":"uuid","type":"string"},"message":{"description":"Comment/message.","type":"string"},"source":{"description":"internal/external/customer.","type":"string"},"toStatus":{"description":"New status.","type":"string"},"type":{"description":"Event type.","type":"string"}},"type":"object"},"ServiceRequestFile":{"properties":{"createdAt":{"format":"date-time","nullable":true,"type":"string"},"filename":{"description":"Original filename.","type":"string"},"id":{"format":"uuid","type":"string"},"mimeType":{"description":"MIME type.","type":"string"},"sizeBytes":{"type":"integer"},"source":{"description":"Upload source.","type":"string"}},"type":"object"},"ServiceRequestFileListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ServiceRequestFile"},"type":"array"}},"type":"object"},"ServiceRequestListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ServiceRequest"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"},"scope":{"$ref":"#/components/schemas/Scope"}},"type":"object"},"ServiceRequestUpdateRequest":{"example":{"comment":"Valmis.","resolution":"Liitos kiristetty ja vuoto tarkistettu.","resolutionReviewed":true,"status":"resolved"},"properties":{"assetId":{"format":"uuid","nullable":true,"type":"string"},"category":{"description":"Category.","type":"string"},"comment":{"description":"History comment.","type":"string"},"customerEmail":{"description":"Customer email.","type":"string"},"customerName":{"description":"Customer name.","type":"string"},"customerPhone":{"description":"Customer phone.","type":"string"},"description":{"description":"New description.","type":"string"},"dueAt":{"description":"YYYY-MM-DD or RFC3339.","type":"string"},"externalRef":{"description":"External ref.","type":"string"},"location":{"description":"Location.","type":"string"},"metadata":{"additionalProperties":true,"type":"object"},"priority":{"description":"Priority.","type":"string"},"reportedByEmail":{"description":"Reporter email.","type":"string"},"reportedByName":{"description":"Reporter name.","type":"string"},"resolution":{"description":"Required when resolving/closing.","type":"string"},"resolutionReviewed":{"type":"boolean"},"status":{"description":"Status.","type":"string"},"title":{"description":"New title.","type":"string"}},"type":"object"},"TelemetryAssetStateResponse":{"properties":{"asset":{"$ref":"#/components/schemas/AssetRef"},"state":{"additionalProperties":true,"type":"object"}},"type":"object"},"TelemetryCapabilitiesResponse":{"properties":{"containerWorkStateEnabled":{"type":"boolean"},"geofenceAlertsEnabled":{"type":"boolean"},"gpsEnabled":{"type":"boolean"},"heartbeatEnabled":{"type":"boolean"},"hourmeterEnabled":{"type":"boolean"},"identifierEnabled":{"type":"boolean"},"imuEnabled":{"type":"boolean"},"messageTypesLast7d":{"additionalProperties":{"type":"integer"},"type":"object"},"scope":{"$ref":"#/components/schemas/Scope"},"telemetryAssets":{"type":"integer"},"telemetryEnabled":{"type":"boolean"},"totalAssets":{"type":"integer"}},"type":"object"},"TelemetryContainerWorkMetric":{"properties":{"asset":{"allOf":[{"$ref":"#/components/schemas/AssetRef"}],"nullable":true},"bucketEnd":{"format":"date-time","type":"string"},"bucketStart":{"format":"date-time","type":"string"},"containerCycleCount":{"type":"integer"},"emptyDistanceM":{"type":"number"},"emptySeconds":{"type":"number"},"groupType":{"enum":["asset","fleet"],"type":"string"},"loadedDistanceM":{"type":"number"},"loadedPercent":{"type":"number"},"loadedSeconds":{"type":"number"}},"type":"object"},"TelemetryContainerWorkResponse":{"properties":{"aggregateRefresh":{"$ref":"#/components/schemas/AggregateRefresh"},"bucket":{"description":"hour or day","type":"string"},"groupBy":{"description":"fleet or asset","type":"string"},"items":{"items":{"$ref":"#/components/schemas/TelemetryContainerWorkMetric"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"},"range":{"$ref":"#/components/schemas/TimeRange"},"source":{"enum":["gold","live"],"type":"string"}},"type":"object"},"TelemetryDataQualityAsset":{"properties":{"adcinEvents":{"type":"integer"},"assetId":{"format":"uuid","type":"string"},"assetTypeName":{"description":"Asset type.","type":"string"},"deviceId":{"description":"Telemetry device id.","type":"string"},"displayCode":{"description":"Asset display code.","type":"string"},"enabled":{"type":"boolean"},"errorMessages":{"type":"integer"},"errorRate":{"type":"number"},"gpsEvents":{"type":"integer"},"gpsOkPercent":{"nullable":true,"type":"number"},"heartbeatEvents":{"type":"integer"},"hourmeterEvents":{"type":"integer"},"identifier":{"description":"Asset identifier.","type":"string"},"imuEvents":{"type":"integer"},"lastAdcinAt":{"format":"date-time","nullable":true,"type":"string"},"lastGpsAt":{"format":"date-time","nullable":true,"type":"string"},"lastHeartbeatAt":{"format":"date-time","nullable":true,"type":"string"},"lastImuAt":{"format":"date-time","nullable":true,"type":"string"},"lastSeenAt":{"format":"date-time","nullable":true,"type":"string"},"messageCount":{"type":"integer"},"name":{"description":"Asset name.","type":"string"},"notes":{"items":{"type":"string"},"type":"array"},"parsedMessages":{"type":"integer"},"silverEvents":{"type":"integer"},"status":{"description":"ok, delayed, offline, silent, poor_gps, errors or disabled.","type":"string"},"statusLabel":{"description":"Human-readable status.","type":"string"},"validGpsEvents":{"type":"integer"}},"type":"object"},"TelemetryDataQualityResponse":{"description":"Telemetry completeness, latest messages, per-message-type counts and recent errors for the requested time range.","properties":{"assets":{"items":{"$ref":"#/components/schemas/TelemetryDataQualityAsset"},"type":"array"},"capabilityState":{"description":"not_configured, configured or configured_no_data.","type":"string"},"from":{"format":"date-time","type":"string"},"generatedAt":{"format":"date-time","type":"string"},"messageTypes":{"items":{"$ref":"#/components/schemas/TelemetryMessageTypeQuality"},"type":"array"},"recentErrors":{"items":{"$ref":"#/components/schemas/TelemetryRecentError"},"type":"array"},"summary":{"properties":{"analyticsUpdatedAt":{"format":"date-time","nullable":true,"type":"string"},"assetsWithData":{"type":"integer"},"coveragePercent":{"type":"number"},"delayedAssets":{"type":"integer"},"errorAssets":{"type":"integer"},"errorMessages":{"type":"integer"},"errorRate":{"type":"number"},"gpsEvents":{"type":"integer"},"gpsOkPercent":{"type":"number"},"messageCount":{"type":"integer"},"offlineAssets":{"type":"integer"},"onlineAssets":{"type":"integer"},"parsedMessages":{"type":"integer"},"poorGpsAssets":{"type":"integer"},"qualityScore":{"type":"number"},"recentErrorCount":{"type":"integer"},"silentAssets":{"type":"integer"},"silverEvents":{"type":"integer"},"telemetryAssets":{"type":"integer"},"totalAssets":{"type":"integer"},"validGpsEvents":{"type":"integer"}},"type":"object"},"telemetryEnabled":{"type":"boolean"},"to":{"format":"date-time","type":"string"}},"type":"object"},"TelemetryDevice":{"properties":{"adcState":{"description":"Raw ADC input state.","type":"string"},"assetDisplayCode":{"description":"Asset display code.","type":"string"},"assetId":{"format":"uuid","type":"string"},"assetIdentifier":{"description":"Asset identifier.","type":"string"},"assetName":{"description":"Asset name.","type":"string"},"containerAttached":{"nullable":true,"type":"boolean"},"deviceId":{"description":"Device identifier.","type":"string"},"displayName":{"description":"Display name.","type":"string"},"enabled":{"type":"boolean"},"firstSeenAt":{"format":"date-time","nullable":true,"type":"string"},"hourmeterValue":{"nullable":true,"type":"integer"},"id":{"format":"uuid","type":"string"},"lastIdentifier":{"description":"Latest RFID/operator identifier.","type":"string"},"lastMessageAt":{"format":"date-time","nullable":true,"type":"string"},"lastMessageType":{"description":"Latest telemetry message type.","type":"string"},"lastSeenAt":{"format":"date-time","nullable":true,"type":"string"},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"notes":{"description":"Notes.","type":"string"},"onlineStatus":{"enum":["online","silent","offline","unknown","disabled"],"type":"string"},"spreaderLocked":{"nullable":true,"type":"boolean"},"workState":{"description":"Derived work state.","type":"string"}},"type":"object"},"TelemetryDeviceListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TelemetryDevice"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"}},"type":"object"},"TelemetryGeofence":{"properties":{"activeAlertCount":{"type":"integer"},"assetCount":{"type":"integer"},"createdAt":{"format":"date-time","nullable":true,"type":"string"},"enabled":{"type":"boolean"},"geometry":{"$ref":"#/components/schemas/GeoJSONGeometry"},"id":{"format":"uuid","type":"string"},"name":{"description":"Geofence name.","type":"string"},"type":{"enum":["allowed","forbidden"],"type":"string"},"updatedAt":{"format":"date-time","nullable":true,"type":"string"}},"type":"object"},"TelemetryGeofenceAlert":{"properties":{"acknowledgedAt":{"format":"date-time","nullable":true,"type":"string"},"alertType":{"description":"forbidden_enter, forbidden_exit etc.","type":"string"},"asset":{"$ref":"#/components/schemas/AssetRef"},"assetId":{"format":"uuid","type":"string"},"createdAt":{"format":"date-time","nullable":true,"type":"string"},"geofenceId":{"format":"uuid","type":"string"},"geofenceName":{"description":"Geofence name.","type":"string"},"id":{"format":"uuid","type":"string"},"isActive":{"type":"boolean"},"resolvedAt":{"format":"date-time","nullable":true,"type":"string"},"status":{"description":"open or acknowledged.","type":"string"}},"type":"object"},"TelemetryGeofenceAlertListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TelemetryGeofenceAlert"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"},"range":{"$ref":"#/components/schemas/TimeRange"}},"type":"object"},"TelemetryGeofenceListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TelemetryGeofence"},"type":"array"}},"type":"object"},"TelemetryIdentifierSession":{"properties":{"asset":{"$ref":"#/components/schemas/AssetRef"},"assetId":{"format":"uuid","type":"string"},"confidence":{"type":"number"},"containerWork":{"$ref":"#/components/schemas/ContainerWorkSummary"},"distanceM":{"type":"number"},"durationSeconds":{"type":"integer"},"endReason":{"description":"End reason.","type":"string"},"endTs":{"format":"date-time","type":"string"},"eventCount":{"type":"integer"},"gpsPointCount":{"type":"integer"},"id":{"format":"uuid","type":"string"},"identifier":{"description":"RFID/operator identifier.","type":"string"},"operatorName":{"description":"Driver/operator name.","type":"string"},"startTs":{"format":"date-time","type":"string"},"stopCount":{"type":"integer"},"tripCount":{"type":"integer"}},"type":"object"},"TelemetryIdentifierSessionListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TelemetryIdentifierSession"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"},"range":{"$ref":"#/components/schemas/TimeRange"}},"type":"object"},"TelemetryMessageTypeQuality":{"properties":{"deviceCount":{"type":"integer"},"errorMessages":{"type":"integer"},"errorRate":{"type":"number"},"messageCount":{"type":"integer"},"messageType":{"description":"Telemetry message type.","type":"string"}},"type":"object"},"TelemetryOperator":{"properties":{"distanceM":{"type":"number"},"durationSeconds":{"type":"integer"},"identifier":{"description":"RFID/operator identifier.","type":"string"},"lastSeenAt":{"format":"date-time","nullable":true,"type":"string"},"operatorName":{"description":"Operator name when known.","type":"string"},"sessionCount":{"type":"integer"}},"type":"object"},"TelemetryOperatorListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TelemetryOperator"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"},"range":{"$ref":"#/components/schemas/TimeRange"}},"type":"object"},"TelemetryPosition":{"properties":{"bucketTs":{"format":"date-time","type":"string"},"lastEventTs":{"format":"date-time","type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"pointCount":{"type":"integer"}},"type":"object"},"TelemetryPositionHistoryResponse":{"properties":{"asset":{"$ref":"#/components/schemas/AssetRef"},"items":{"items":{"$ref":"#/components/schemas/TelemetryPosition"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"},"range":{"$ref":"#/components/schemas/TimeRange"},"resolution":{"enum":["15min","1min"],"type":"string"},"source":{"description":"Position history is returned from precomputed telemetry aggregates.","enum":["gold"],"type":"string"}},"type":"object"},"TelemetryRecentError":{"properties":{"deviceId":{"description":"Device id.","type":"string"},"ingestError":{"description":"Parser/ingest error.","type":"string"},"messageType":{"description":"Message type.","type":"string"},"payloadSample":{"description":"Truncated payload sample for troubleshooting.","type":"string"},"receivedAt":{"format":"date-time","type":"string"},"subject":{"description":"Source subject/topic.","type":"string"}},"type":"object"},"TelemetryServiceRequestMetric":{"properties":{"asset":{"allOf":[{"$ref":"#/components/schemas/AssetRef"}],"nullable":true},"bucketEnd":{"format":"date-time","type":"string"},"bucketStart":{"format":"date-time","type":"string"},"closedCount":{"type":"integer"},"groupType":{"enum":["asset","fleet"],"type":"string"},"highPriorityCount":{"type":"integer"},"openCount":{"type":"integer"},"resolvedCount":{"type":"integer"},"totalCount":{"type":"integer"},"urgentPriorityCount":{"type":"integer"}},"type":"object"},"TelemetryServiceRequestMetricsResponse":{"properties":{"aggregateRefresh":{"$ref":"#/components/schemas/AggregateRefresh"},"bucket":{"description":"hour or day","type":"string"},"groupBy":{"description":"fleet or asset","type":"string"},"items":{"items":{"$ref":"#/components/schemas/TelemetryServiceRequestMetric"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"},"range":{"$ref":"#/components/schemas/TimeRange"},"source":{"enum":["gold","live"],"type":"string"}},"type":"object"},"TelemetryUsageSession":{"properties":{"asset":{"$ref":"#/components/schemas/AssetRef"},"assetId":{"format":"uuid","type":"string"},"confidence":{"type":"number"},"containerWork":{"$ref":"#/components/schemas/ContainerWorkSummary"},"deviceId":{"description":"Telemetry device id.","type":"string"},"distanceM":{"type":"number"},"durationSeconds":{"type":"integer"},"endReason":{"description":"Session end reason.","type":"string"},"endTs":{"format":"date-time","type":"string"},"hourmeterDelta":{"nullable":true,"type":"integer"},"id":{"format":"uuid","type":"string"},"identifier":{"description":"RFID/operator identifier.","type":"string"},"imuAnomalyCount":{"type":"integer"},"imuSampleCount":{"type":"integer"},"movingSeconds":{"type":"integer"},"operatorName":{"description":"Driver/operator name.","type":"string"},"startReason":{"description":"Session start reason.","type":"string"},"startTs":{"format":"date-time","type":"string"},"stationaryRunningSeconds":{"type":"integer"},"stopCount":{"type":"integer"},"tripCount":{"type":"integer"}},"type":"object"},"TelemetryUsageSessionListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TelemetryUsageSession"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"},"range":{"$ref":"#/components/schemas/TimeRange"}},"type":"object"},"TelemetryUtilizationMetric":{"properties":{"asset":{"allOf":[{"$ref":"#/components/schemas/AssetRef"}],"nullable":true},"bucketEnd":{"format":"date-time","type":"string"},"bucketStart":{"format":"date-time","type":"string"},"containerWork":{"$ref":"#/components/schemas/ContainerWorkSummary"},"distanceM":{"type":"number"},"groupType":{"enum":["asset","fleet"],"type":"string"},"hourmeterDelta":{"type":"number"},"idlePercent":{"type":"number"},"runningSeconds":{"type":"number"},"stationaryRunningSeconds":{"type":"number"},"utilizationPercent":{"type":"number"}},"type":"object"},"TelemetryUtilizationResponse":{"properties":{"aggregateRefresh":{"$ref":"#/components/schemas/AggregateRefresh"},"bucket":{"description":"hour or day","type":"string"},"groupBy":{"description":"fleet or asset","type":"string"},"items":{"items":{"$ref":"#/components/schemas/TelemetryUtilizationMetric"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"},"range":{"$ref":"#/components/schemas/TimeRange"},"source":{"enum":["gold","live"],"type":"string"}},"type":"object"},"TimeRange":{"properties":{"from":{"format":"date-time","nullable":true,"type":"string"},"to":{"format":"date-time","nullable":true,"type":"string"}},"type":"object"},"WebhookDelivery":{"properties":{"attemptCount":{"type":"integer"},"createdAt":{"format":"date-time","nullable":true,"type":"string"},"deliveredAt":{"format":"date-time","nullable":true,"type":"string"},"entityId":{"format":"uuid","nullable":true,"type":"string"},"entityType":{"description":"Entity type.","type":"string"},"error":{"description":"Error text.","type":"string"},"eventType":{"description":"Event type.","type":"string"},"httpStatus":{"nullable":true,"type":"integer"},"id":{"format":"uuid","type":"string"},"lastAttemptAt":{"format":"date-time","nullable":true,"type":"string"},"maxAttempts":{"type":"integer"},"nextAttemptAt":{"format":"date-time","nullable":true,"type":"string"},"status":{"description":"Delivery status.","type":"string"},"url":{"description":"Delivery URL.","type":"string"},"webhookId":{"description":"Webhook id.","type":"string"}},"type":"object"},"WebhookDeliveryContract":{"properties":{"attemptHeader":{"example":"X-Sarka-Webhook-Attempt","type":"string"},"contentType":{"enum":["application/json"],"type":"string"},"headers":{"items":{"type":"string"},"type":"array"},"idHeader":{"example":"X-Sarka-Webhook-Id","type":"string"},"method":{"enum":["POST"],"type":"string"},"retryStrategy":{"$ref":"#/components/schemas/WebhookRetryStrategy"},"signatureAlgorithm":{"enum":["hmac-sha256"],"type":"string"},"signatureFormat":{"example":"sha256=\u003chex\u003e","type":"string"},"signatureHeader":{"example":"X-Sarka-Signature","type":"string"},"signedContent":{"description":"The HMAC is calculated over the raw JSON request body bytes.","enum":["raw_body"],"type":"string"},"successStatusCodes":{"example":["2xx"],"items":{"type":"string"},"type":"array"},"timeoutSeconds":{"example":10,"type":"integer"},"timestampHeader":{"example":"X-Sarka-Webhook-Timestamp","type":"string"}},"required":["method","contentType","signatureHeader","signatureAlgorithm","timestampHeader","retryStrategy"],"type":"object"},"WebhookDeliveryListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/WebhookDelivery"},"type":"array"},"paging":{"$ref":"#/components/schemas/Paging"}},"type":"object"},"WebhookEvent":{"properties":{"id":{"description":"Event name.","type":"string"},"label":{"description":"Human label.","type":"string"}},"type":"object"},"WebhookEventListResponse":{"properties":{"delivery":{"$ref":"#/components/schemas/WebhookDeliveryContract"},"items":{"items":{"$ref":"#/components/schemas/WebhookEvent"},"type":"array"},"payload":{"$ref":"#/components/schemas/WebhookPayload"}},"type":"object"},"WebhookPayload":{"properties":{"createdAt":{"format":"date-time","nullable":true,"type":"string"},"data":{"additionalProperties":true,"type":"object"},"entityId":{"format":"uuid","nullable":true,"type":"string"},"entityType":{"description":"Entity type, for example service_request.","type":"string"},"event":{"description":"Webhook event type, for example service_request.created.","type":"string"},"tenantId":{"format":"uuid","type":"string"}},"required":["event","entityType","tenantId","createdAt","data"],"type":"object"},"WebhookRetryStrategy":{"properties":{"backoffSeconds":{"example":[15,60],"items":{"type":"integer"},"type":"array"},"maxAttempts":{"example":3,"type":"integer"}},"required":["maxAttempts","backoffSeconds"],"type":"object"},"WebhookSubscription":{"properties":{"createdAt":{"description":"RFC3339 timestamp.","type":"string"},"enabled":{"type":"boolean"},"events":{"items":{"type":"string"},"type":"array"},"id":{"description":"Webhook id.","type":"string"},"name":{"description":"Webhook name.","type":"string"},"secretPreview":{"description":"Masked secret preview.","type":"string"},"secretSet":{"type":"boolean"},"url":{"description":"Delivery URL.","type":"string"}},"type":"object"},"WebhookSubscriptionListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/WebhookSubscription"},"type":"array"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"Tenant or customerName-scoped API key generated in tenant settings.","in":"header","name":"X-API-Key","type":"apiKey"}}},"info":{"contact":{"email":"support@sarkahq.com","name":"Sarka API Support","url":"https://sarkahq.com"},"description":"Production-grade external API for Sarka reporting, telemetry metrics, service requests and exports. Authentication uses X-API-Key. Tenant keys see the whole tenant; customer keys are restricted by exact customerName scope. Timestamps are UTC RFC3339. JSON list endpoints are paginated with limit/offset. Telemetry exports are explicitly paginated and expose X-Export-* continuation headers.","title":"Sarka External API","version":"1.0.0"},"openapi":"3.0.3","paths":{"/":{"get":{"deprecated":true,"description":"Customer-facing public API documentation with quick starts, query recipes, export guidance, webhook notes and production checklist.","operationId":"getExternalPublicGuideRoot","responses":{"200":{"description":"HTML documentation page."}},"security":[],"summary":"Public API documentation","tags":["Documentation"]}},"/assets":{"get":{"deprecated":true,"description":"Deprecated alias for /reporting/assets. Use /reporting/assets for new integrations.","operationId":"listExternalAssetsAlias","parameters":[{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Filter by resource status. For assets this is the operational status; for inspections and reports this is the resource status.","in":"query","name":"status","required":false,"schema":{"type":"string"}},{"description":"Tenant keys may use this to narrow service requests to a customerName. Customer-scoped keys are already restricted automatically.","in":"query","name":"customerName","required":false,"schema":{"type":"string"}},{"description":"Filter assets by exact asset type name.","in":"query","name":"assetType","required":false,"schema":{"type":"string"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingAssetListResponse"}}},"description":"Deprecated alias for /reporting/assets. Use /reporting/assets for new integrations."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List assets alias","tags":["Reporting"]}},"/docs":{"get":{"description":"OpenAPI reference for all Sarka External API v1 endpoints, request parameters, response schemas and integration examples.","operationId":"getExternalDocs","responses":{"200":{"description":"HTML documentation page."}},"security":[],"summary":"Swagger/OpenAPI reference","tags":["Documentation"]}},"/guide":{"get":{"description":"Customer-facing public API documentation with quick starts, query recipes, export guidance, webhook notes and production checklist.","operationId":"getExternalPublicGuide","responses":{"200":{"description":"HTML documentation page."}},"security":[],"summary":"Public API documentation","tags":["Documentation"]}},"/me":{"get":{"description":"Use this first to verify that the key works, which tenant it belongs to and whether it is customerName-scoped.","operationId":"getExternalAPIScope","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}},"description":"Use this first to verify that the key works, which tenant it belongs to and whether it is customerName-scoped."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Inspect current API key scope","tags":["Authentication"]}},"/openapi.json":{"get":{"description":"Machine-readable OpenAPI 3.0 specification for Swagger/OpenAPI tools, code generation and API clients.","operationId":"getExternalOpenAPI","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAPIObject"}}},"description":"OpenAPI JSON document."}},"security":[],"summary":"OpenAPI specification","tags":["Documentation"]}},"/public-docs":{"get":{"deprecated":true,"description":"Alias for /guide.","operationId":"getExternalPublicDocs","responses":{"200":{"description":"HTML documentation page."}},"security":[],"summary":"Public API documentation alias","tags":["Documentation"]}},"/reporting/asset-types":{"get":{"description":"Reference-data endpoint for integration UIs. Customer-scoped keys see only asset types used by their visible assets.","operationId":"listReportingAssetTypes","parameters":[{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingAssetTypeListResponse"}}},"description":"Reference-data endpoint for integration UIs. Customer-scoped keys see only asset types used by their visible assets."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List asset types","tags":["Reporting reference data"]}},"/reporting/assets":{"get":{"description":"Assets visible to the API key scope. Supports q, status, customerName and assetType filters so clients do not need to scan the full asset list client-side.","operationId":"listReportingAssets","parameters":[{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Filter by resource status. For assets this is the operational status; for inspections and reports this is the resource status.","in":"query","name":"status","required":false,"schema":{"type":"string"}},{"description":"Tenant keys may use this to narrow service requests to a customerName. Customer-scoped keys are already restricted automatically.","in":"query","name":"customerName","required":false,"schema":{"type":"string"}},{"description":"Filter assets by exact asset type name.","in":"query","name":"assetType","required":false,"schema":{"type":"string"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingAssetListResponse"}}},"description":"Assets visible to the API key scope. Supports q, status, customerName and assetType filters so clients do not need to scan the full asset list client-side."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List assets with reporting metadata","tags":["Reporting"]}},"/reporting/assets/{id}":{"get":{"description":"Returns one asset with latest reporting metadata when visible to the tenant/customerName scope.","operationId":"getReportingAsset","parameters":[{"description":"Asset UUID.","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingAsset"}}},"description":"Returns one asset with latest reporting metadata when visible to the tenant/customerName scope."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Get one asset","tags":["Reporting"]}},"/reporting/export.csv":{"get":{"description":"CSV export of reporting rows for the selected range.","operationId":"exportReportingCSV","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}}],"responses":{"200":{"content":{"text/csv":{"schema":{"format":"binary","type":"string"}}},"description":"CSV file.","headers":{"X-Export-Limit":{"description":"Maximum number of rows returned by this export response.","schema":{"type":"integer"}},"X-Export-Offset":{"description":"Offset used for this export response.","schema":{"type":"integer"}},"X-Export-Truncated":{"description":"true when more rows are available and the client must call again with X-Next-Offset.","schema":{"type":"boolean"}},"X-Next-Offset":{"description":"Next offset when X-Export-Truncated is true.","schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid range or filter."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing or invalid X-API-Key."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Export reporting as CSV","tags":["Reporting"]}},"/reporting/export.xlsx":{"get":{"description":"Excel export of reporting rows for the selected range.","operationId":"exportReportingXLSX","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}}],"responses":{"200":{"content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"format":"binary","type":"string"}}},"description":"XLSX file.","headers":{"X-Export-Limit":{"description":"Maximum number of rows returned by this export response.","schema":{"type":"integer"}},"X-Export-Offset":{"description":"Offset used for this export response.","schema":{"type":"integer"}},"X-Export-Truncated":{"description":"true when more rows are available and the client must call again with X-Next-Offset.","schema":{"type":"boolean"}},"X-Next-Offset":{"description":"Next offset when X-Export-Truncated is true.","schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid range or filter."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing or invalid X-API-Key."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Export reporting as Excel","tags":["Reporting"]}},"/reporting/inspections":{"get":{"description":"Inspection records in the selected range. Supports status, assetId, customerName, outcome, impact and q filters.","operationId":"listReportingInspections","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Filter by resource status. For assets this is the operational status; for inspections and reports this is the resource status.","in":"query","name":"status","required":false,"schema":{"type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Tenant keys may use this to narrow service requests to a customerName. Customer-scoped keys are already restricted automatically.","in":"query","name":"customerName","required":false,"schema":{"type":"string"}},{"description":"Filter inspection/report outcome, for example completed or rejected.","in":"query","name":"outcome","required":false,"schema":{"type":"string"}},{"description":"Filter report impact, for example warning or out_of_service.","in":"query","name":"impact","required":false,"schema":{"type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingInspectionListResponse"}}},"description":"Inspection records in the selected range. Supports status, assetId, customerName, outcome, impact and q filters."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List inspections","tags":["Reporting"]}},"/reporting/inspections/{id}":{"get":{"description":"Returns one inspection with linked asset, template, report summary and media counters.","operationId":"getReportingInspection","parameters":[{"description":"Inspection UUID.","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingInspection"}}},"description":"Returns one inspection with linked asset, template, report summary and media counters."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Get one inspection","tags":["Reporting"]}},"/reporting/overview":{"get":{"description":"Summary counters, breakdowns, monthly trend and recent reports/service requests for the tenant or customerName scope.","operationId":"getReportingOverview","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingOverviewResponse"}}},"description":"Summary counters, breakdowns, monthly trend and recent reports/service requests for the tenant or customerName scope."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Get reporting overview","tags":["Reporting"]}},"/reporting/reports":{"get":{"description":"Generated inspection reports in the selected report-created range. Supports status, assetId, customerName, outcome, impact and q filters.","operationId":"listReportingReports","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Filter by resource status. For assets this is the operational status; for inspections and reports this is the resource status.","in":"query","name":"status","required":false,"schema":{"type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Tenant keys may use this to narrow service requests to a customerName. Customer-scoped keys are already restricted automatically.","in":"query","name":"customerName","required":false,"schema":{"type":"string"}},{"description":"Filter inspection/report outcome, for example completed or rejected.","in":"query","name":"outcome","required":false,"schema":{"type":"string"}},{"description":"Filter report impact, for example warning or out_of_service.","in":"query","name":"impact","required":false,"schema":{"type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingReportListResponse"}}},"description":"Generated inspection reports in the selected report-created range. Supports status, assetId, customerName, outcome, impact and q filters."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List reports","tags":["Reporting"]}},"/reporting/reports/{id}":{"get":{"description":"Returns one generated report summary when visible to the current tenant/customerName scope.","operationId":"getReportingReport","parameters":[{"description":"Report UUID.","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingReport"}}},"description":"Returns one generated report summary when visible to the current tenant/customerName scope."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Get one report","tags":["Reporting"]}},"/reporting/templates":{"get":{"description":"Reference-data endpoint for integration UIs and customer portals. Customer-scoped keys see templates associated with visible asset types.","operationId":"listReportingTemplates","parameters":[{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Filter templates by status, for example draft or active.","in":"query","name":"status","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingTemplateListResponse"}}},"description":"Reference-data endpoint for integration UIs and customer portals. Customer-scoped keys see templates associated with visible asset types."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List inspection templates","tags":["Reporting reference data"]}},"/service-requests":{"get":{"description":"Lists service requests in the current tenant/customerName scope. Tenant keys may additionally filter with customerName.","operationId":"listServiceRequests","parameters":[{"description":"Filter by status.","in":"query","name":"status","required":false,"schema":{"enum":["new","reopened","triaged","in_progress","waiting_customer","resolved","closed","cancelled"],"type":"string"}},{"description":"Tenant keys may use this to narrow service requests to a customerName. Customer-scoped keys are already restricted automatically.","in":"query","name":"customerName","required":false,"schema":{"type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceRequestListResponse"}}},"description":"Lists service requests in the current tenant/customerName scope. Tenant keys may additionally filter with customerName."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List service requests","tags":["Service requests"]},"post":{"description":"Creates a new service request from an external system or customer portal. For customer-scoped keys, customerName defaults to the key scope. Use Idempotency-Key for safe retries.","operationId":"createServiceRequest","parameters":[{"description":"Optional idempotency key for safe retries of POST /service-requests and PATCH /service-requests/{id}. Reusing the same key with the same request returns the original response; reusing it with a different body returns 409.","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":200,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceRequestCreateRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IDResponse"}}},"description":"Creates a new service request from an external system or customer portal. For customer-scoped keys, customerName defaults to the key scope."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Create a service request","tags":["Service requests"]}},"/service-requests/{id}":{"delete":{"description":"Hard delete is only allowed for an erroneous, new and untouched service request. Processed requests must be cancelled instead.","operationId":"deleteServiceRequest","parameters":[{"description":"Service request UUID.","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResponse"}}},"description":"Deleted."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Delete an untouched new service request","tags":["Service requests"]},"get":{"description":"Returns one service request with history and files when visible to the current scope.","operationId":"getServiceRequest","parameters":[{"description":"Service request UUID.","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceRequest"}}},"description":"Returns one service request with history and files when visible to the current scope."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Get one service request","tags":["Service requests"]},"patch":{"description":"Updates fields, status and optional comment. Resolving or closing requires resolution and resolutionReviewed=true. Use Idempotency-Key for safe retries of status transitions.","operationId":"updateServiceRequest","parameters":[{"description":"Service request UUID.","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Optional idempotency key for safe retries of POST /service-requests and PATCH /service-requests/{id}. Reusing the same key with the same request returns the original response; reusing it with a different body returns 409.","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":200,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceRequestUpdateRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IDResponse"}}},"description":"Updates fields, status and optional comment. Resolving or closing requires resolution and resolutionReviewed=true."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Update a service request","tags":["Service requests"]}},"/service-requests/{id}/cancel":{"post":{"description":"Cancels a service request with a required reason. Use this instead of permanent deletion after processing has started.","operationId":"cancelServiceRequest","parameters":[{"description":"Service request UUID.","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceRequestCancelRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelResponse"}}},"description":"Cancels a service request with a required reason. Use this instead of permanent deletion after processing has started."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Cancel a processed service request","tags":["Service requests"]}},"/service-requests/{id}/files":{"get":{"description":"Lists files attached to a service request.","operationId":"listServiceRequestFiles","parameters":[{"description":"Service request UUID.","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceRequestFileListResponse"}}},"description":"Lists files attached to a service request."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List service request files","tags":["Service request files"]},"post":{"description":"Uploads one multipart/form-data file field named file.","operationId":"uploadServiceRequestFile","parameters":[{"description":"Service request UUID.","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/FileUploadRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUploadResponse"}}},"description":"Uploaded file metadata."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Upload a service request file","tags":["Service request files"]}},"/service-requests/{id}/files/{fileId}":{"get":{"description":"Streams the original service request file when visible in the current scope.","operationId":"downloadServiceRequestFile","parameters":[{"description":"Service request UUID.","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"File UUID.","in":"path","name":"fileId","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"description":"File stream."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid id."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the file."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"File not found."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Download a service request file","tags":["Service request files"]}},"/swagger":{"get":{"deprecated":true,"description":"Alias for /docs.","operationId":"getExternalSwagger","responses":{"200":{"description":"HTML documentation page."}},"security":[],"summary":"Swagger/OpenAPI reference alias","tags":["Documentation"]}},"/telemetry/assets/{assetId}/positions":{"get":{"description":"Precomputed position history for map drawing and route views. Uses 15-minute resolution by default; 1-minute resolution is intended for short, detailed time ranges.","operationId":"listTelemetryAssetPositions","parameters":[{"description":"Asset UUID.","in":"path","name":"assetId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Position history resolution. 15min is recommended for maps and exports; 1min is intended for short, detailed time ranges.","in":"query","name":"resolution","required":false,"schema":{"default":"15min","enum":["15min","1min"],"type":"string"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryPositionHistoryResponse"}}},"description":"Precomputed position history for map drawing and route views. Uses 15-minute resolution by default; 1-minute resolution is intended for short, detailed time ranges."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List asset position history","tags":["Telemetry"]}},"/telemetry/assets/{assetId}/state":{"get":{"description":"Latest materialized telemetry state for one asset, including position/hourmeter/work-state fields when available.","operationId":"getTelemetryAssetState","parameters":[{"description":"Asset UUID.","in":"path","name":"assetId","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryAssetStateResponse"}}},"description":"Latest materialized telemetry state for one asset, including position/hourmeter/work-state fields when available."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Get latest telemetry state for an asset","tags":["Telemetry"]}},"/telemetry/capabilities":{"get":{"description":"Shows whether the current scope has telemetry assets and which message types have been seen during the last seven days.","operationId":"getTelemetryCapabilities","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryCapabilitiesResponse"}}},"description":"Shows whether the current scope has telemetry assets and which message types have been seen during the last seven days."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Get telemetry capabilities","tags":["Telemetry"]}},"/telemetry/container-work":{"get":{"description":"Loaded/empty work metrics for container cranes and reach stackers. adcin=on means the spreader/locking mechanism is locked or container engaged; adcin=off means open/empty.","operationId":"getTelemetryContainerWork","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Aggregation bucket. Hour and day buckets use precomputed aggregates when available.","in":"query","name":"bucket","required":false,"schema":{"default":"day","enum":["hour","day"],"type":"string"}},{"description":"Aggregate by one row per bucket for the whole scope, or one row per asset and bucket.","in":"query","name":"groupBy","required":false,"schema":{"default":"fleet","enum":["fleet","asset"],"type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Include buckets without activity. For groupBy=asset, large scopes require assetId or q to avoid enormous result sets.","in":"query","name":"includeZero","required":false,"schema":{"default":false,"type":"boolean"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryContainerWorkResponse"}}},"description":"Loaded/empty work metrics for container cranes and reach stackers. adcin=on means the spreader/locking mechanism is locked or container engaged; adcin=off means open/empty."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Get container work metrics","tags":["Telemetry metrics"]}},"/telemetry/container-work/export.csv":{"get":{"description":"Paginated CSV export of loaded/empty container work metrics.","operationId":"exportContainerWorkCSV","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Aggregation bucket. Hour and day buckets use precomputed aggregates when available.","in":"query","name":"bucket","required":false,"schema":{"default":"day","enum":["hour","day"],"type":"string"}},{"description":"Aggregate by one row per bucket for the whole scope, or one row per asset and bucket.","in":"query","name":"groupBy","required":false,"schema":{"default":"fleet","enum":["fleet","asset"],"type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Export page size. Default and maximum 50000 rows.","in":"query","name":"limit","required":false,"schema":{"default":50000,"maximum":50000,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"text/csv":{"schema":{"format":"binary","type":"string"}}},"description":"CSV file.","headers":{"X-Export-Limit":{"description":"Maximum number of rows returned by this export response.","schema":{"type":"integer"}},"X-Export-Offset":{"description":"Offset used for this export response.","schema":{"type":"integer"}},"X-Export-Truncated":{"description":"true when more rows are available and the client must call again with X-Next-Offset.","schema":{"type":"boolean"}},"X-Next-Offset":{"description":"Next offset when X-Export-Truncated is true.","schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid range or filter."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing or invalid X-API-Key."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Export container work as CSV","tags":["Telemetry exports"]}},"/telemetry/container-work/export.xlsx":{"get":{"description":"Paginated Excel export of loaded/empty container work metrics.","operationId":"exportContainerWorkXLSX","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Aggregation bucket. Hour and day buckets use precomputed aggregates when available.","in":"query","name":"bucket","required":false,"schema":{"default":"day","enum":["hour","day"],"type":"string"}},{"description":"Aggregate by one row per bucket for the whole scope, or one row per asset and bucket.","in":"query","name":"groupBy","required":false,"schema":{"default":"fleet","enum":["fleet","asset"],"type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Export page size. Default and maximum 50000 rows.","in":"query","name":"limit","required":false,"schema":{"default":50000,"maximum":50000,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"format":"binary","type":"string"}}},"description":"XLSX file.","headers":{"X-Export-Limit":{"description":"Maximum number of rows returned by this export response.","schema":{"type":"integer"}},"X-Export-Offset":{"description":"Offset used for this export response.","schema":{"type":"integer"}},"X-Export-Truncated":{"description":"true when more rows are available and the client must call again with X-Next-Offset.","schema":{"type":"boolean"}},"X-Next-Offset":{"description":"Next offset when X-Export-Truncated is true.","schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid range or filter."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing or invalid X-API-Key."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Export container work as Excel","tags":["Telemetry exports"]}},"/telemetry/data-quality":{"get":{"description":"Data quality snapshot for the current scope: latest message timestamps, message-type counts and recent processing errors.","operationId":"getTelemetryDataQuality","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryDataQualityResponse"}}},"description":"Data quality snapshot for the current scope: latest message timestamps, message-type counts and recent processing errors."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Get telemetry data quality","tags":["Telemetry"]}},"/telemetry/devices":{"get":{"description":"Lists telemetry-enabled assets and devices with latest state, online status and last message metadata. The status filter is applied before pagination.","operationId":"listTelemetryDevices","parameters":[{"description":"Telemetry online status.","in":"query","name":"status","required":false,"schema":{"default":"all","enum":["all","online","silent","offline","unknown","disabled"],"type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryDeviceListResponse"}}},"description":"Lists telemetry-enabled assets and devices with latest state, online status and last message metadata. The status filter is applied before pagination."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List telemetry devices","tags":["Telemetry"]}},"/telemetry/geofence-alerts":{"get":{"description":"Read-only feed of geofence alerts visible to the API key scope.","operationId":"listTelemetryGeofenceAlerts","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Restrict to one geofence UUID.","in":"query","name":"geofenceId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Acknowledgement status.","in":"query","name":"status","required":false,"schema":{"default":"all","enum":["all","open","acknowledged"],"type":"string"}},{"description":"Active/resolved state.","in":"query","name":"active","required":false,"schema":{"default":"all","enum":["all","active","resolved","true","false"],"type":"string"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryGeofenceAlertListResponse"}}},"description":"Read-only feed of geofence alerts visible to the API key scope."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List geofence alerts","tags":["Telemetry"]}},"/telemetry/geofences":{"get":{"description":"Lists geofence definitions visible to the current scope. Customer-scoped keys see geofences linked to their visible assets.","operationId":"listTelemetryGeofences","parameters":[{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Geofence type.","in":"query","name":"type","required":false,"schema":{"default":"all","enum":["all","allowed","forbidden"],"type":"string"}},{"description":"Enabled filter.","in":"query","name":"enabled","required":false,"schema":{"default":"all","enum":["all","true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryGeofenceListResponse"}}},"description":"Lists geofence definitions visible to the current scope. Customer-scoped keys see geofences linked to their visible assets."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List geofences","tags":["Telemetry reference data"]}},"/telemetry/identifier-sessions":{"get":{"description":"Materialized RFID/operator sessions. Time filtering is overlap-based. Use identifier for exact tag/operator filtering.","operationId":"listTelemetryIdentifierSessions","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Exact RFID/operator identifier filter for identifier sessions.","in":"query","name":"identifier","required":false,"schema":{"type":"string"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryIdentifierSessionListResponse"}}},"description":"Materialized RFID/operator sessions. Time filtering is overlap-based. Use identifier for exact tag/operator filtering."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List identifier/operator sessions","tags":["Telemetry"]}},"/telemetry/identifier-sessions/export.csv":{"get":{"description":"Paginated CSV export of RFID/operator sessions.","operationId":"exportIdentifierSessionsCSV","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Exact RFID/operator identifier filter for identifier sessions.","in":"query","name":"identifier","required":false,"schema":{"type":"string"}},{"description":"Export page size. Default and maximum 50000 rows.","in":"query","name":"limit","required":false,"schema":{"default":50000,"maximum":50000,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"text/csv":{"schema":{"format":"binary","type":"string"}}},"description":"CSV file.","headers":{"X-Export-Limit":{"description":"Maximum number of rows returned by this export response.","schema":{"type":"integer"}},"X-Export-Offset":{"description":"Offset used for this export response.","schema":{"type":"integer"}},"X-Export-Truncated":{"description":"true when more rows are available and the client must call again with X-Next-Offset.","schema":{"type":"boolean"}},"X-Next-Offset":{"description":"Next offset when X-Export-Truncated is true.","schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid range or filter."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing or invalid X-API-Key."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Export identifier sessions as CSV","tags":["Telemetry exports"]}},"/telemetry/identifier-sessions/export.xlsx":{"get":{"description":"Paginated Excel export of RFID/operator sessions.","operationId":"exportIdentifierSessionsXLSX","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Exact RFID/operator identifier filter for identifier sessions.","in":"query","name":"identifier","required":false,"schema":{"type":"string"}},{"description":"Export page size. Default and maximum 50000 rows.","in":"query","name":"limit","required":false,"schema":{"default":50000,"maximum":50000,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"format":"binary","type":"string"}}},"description":"XLSX file.","headers":{"X-Export-Limit":{"description":"Maximum number of rows returned by this export response.","schema":{"type":"integer"}},"X-Export-Offset":{"description":"Offset used for this export response.","schema":{"type":"integer"}},"X-Export-Truncated":{"description":"true when more rows are available and the client must call again with X-Next-Offset.","schema":{"type":"boolean"}},"X-Next-Offset":{"description":"Next offset when X-Export-Truncated is true.","schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid range or filter."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing or invalid X-API-Key."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Export identifier sessions as Excel","tags":["Telemetry exports"]}},"/telemetry/operators":{"get":{"description":"Lists RFID/operator identifiers observed in materialized identifier sessions, with summary activity counters.","operationId":"listTelemetryOperators","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryOperatorListResponse"}}},"description":"Lists RFID/operator identifiers observed in materialized identifier sessions, with summary activity counters."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List operators/identifiers","tags":["Telemetry reference data"]}},"/telemetry/service-request-metrics":{"get":{"description":"Hourly or daily service request counts by fleet or asset. Useful for maintenance load reporting and customer SLA dashboards.","operationId":"getTelemetryServiceRequestMetrics","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Aggregation bucket. Hour and day buckets use precomputed aggregates when available.","in":"query","name":"bucket","required":false,"schema":{"default":"day","enum":["hour","day"],"type":"string"}},{"description":"Aggregate by one row per bucket for the whole scope, or one row per asset and bucket.","in":"query","name":"groupBy","required":false,"schema":{"default":"fleet","enum":["fleet","asset"],"type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Include buckets without activity. For groupBy=asset, large scopes require assetId or q to avoid enormous result sets.","in":"query","name":"includeZero","required":false,"schema":{"default":false,"type":"boolean"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryServiceRequestMetricsResponse"}}},"description":"Hourly or daily service request counts by fleet or asset. Useful for maintenance load reporting and customer SLA dashboards."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Get service request metrics","tags":["Telemetry metrics"]}},"/telemetry/service-request-metrics/export.csv":{"get":{"description":"Paginated CSV export of service request metrics.","operationId":"exportServiceRequestMetricsCSV","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Aggregation bucket. Hour and day buckets use precomputed aggregates when available.","in":"query","name":"bucket","required":false,"schema":{"default":"day","enum":["hour","day"],"type":"string"}},{"description":"Aggregate by one row per bucket for the whole scope, or one row per asset and bucket.","in":"query","name":"groupBy","required":false,"schema":{"default":"fleet","enum":["fleet","asset"],"type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Export page size. Default and maximum 50000 rows.","in":"query","name":"limit","required":false,"schema":{"default":50000,"maximum":50000,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"text/csv":{"schema":{"format":"binary","type":"string"}}},"description":"CSV file.","headers":{"X-Export-Limit":{"description":"Maximum number of rows returned by this export response.","schema":{"type":"integer"}},"X-Export-Offset":{"description":"Offset used for this export response.","schema":{"type":"integer"}},"X-Export-Truncated":{"description":"true when more rows are available and the client must call again with X-Next-Offset.","schema":{"type":"boolean"}},"X-Next-Offset":{"description":"Next offset when X-Export-Truncated is true.","schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid range or filter."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing or invalid X-API-Key."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Export service request metrics as CSV","tags":["Telemetry exports"]}},"/telemetry/service-request-metrics/export.xlsx":{"get":{"description":"Paginated Excel export of service request metrics.","operationId":"exportServiceRequestMetricsXLSX","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Aggregation bucket. Hour and day buckets use precomputed aggregates when available.","in":"query","name":"bucket","required":false,"schema":{"default":"day","enum":["hour","day"],"type":"string"}},{"description":"Aggregate by one row per bucket for the whole scope, or one row per asset and bucket.","in":"query","name":"groupBy","required":false,"schema":{"default":"fleet","enum":["fleet","asset"],"type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Export page size. Default and maximum 50000 rows.","in":"query","name":"limit","required":false,"schema":{"default":50000,"maximum":50000,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"format":"binary","type":"string"}}},"description":"XLSX file.","headers":{"X-Export-Limit":{"description":"Maximum number of rows returned by this export response.","schema":{"type":"integer"}},"X-Export-Offset":{"description":"Offset used for this export response.","schema":{"type":"integer"}},"X-Export-Truncated":{"description":"true when more rows are available and the client must call again with X-Next-Offset.","schema":{"type":"boolean"}},"X-Next-Offset":{"description":"Next offset when X-Export-Truncated is true.","schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid range or filter."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing or invalid X-API-Key."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Export service request metrics as Excel","tags":["Telemetry exports"]}},"/telemetry/usage-sessions":{"get":{"description":"Materialized machine usage sessions. Time filtering is overlap-based: sessions that started before from but ended inside the range are included.","operationId":"listTelemetryUsageSessions","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryUsageSessionListResponse"}}},"description":"Materialized machine usage sessions. Time filtering is overlap-based: sessions that started before from but ended inside the range are included."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List usage sessions","tags":["Telemetry"]}},"/telemetry/usage-sessions/export.csv":{"get":{"description":"Paginated CSV export. Check X-Export-Truncated and continue with offset when true.","operationId":"exportUsageSessionsCSV","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Export page size. Default and maximum 50000 rows.","in":"query","name":"limit","required":false,"schema":{"default":50000,"maximum":50000,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"text/csv":{"schema":{"format":"binary","type":"string"}}},"description":"CSV file.","headers":{"X-Export-Limit":{"description":"Maximum number of rows returned by this export response.","schema":{"type":"integer"}},"X-Export-Offset":{"description":"Offset used for this export response.","schema":{"type":"integer"}},"X-Export-Truncated":{"description":"true when more rows are available and the client must call again with X-Next-Offset.","schema":{"type":"boolean"}},"X-Next-Offset":{"description":"Next offset when X-Export-Truncated is true.","schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid range or filter."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing or invalid X-API-Key."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Export usage sessions as CSV","tags":["Telemetry exports"]}},"/telemetry/usage-sessions/export.xlsx":{"get":{"description":"Paginated Excel export. Check X-Export-Truncated and continue with offset when true.","operationId":"exportUsageSessionsXLSX","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Export page size. Default and maximum 50000 rows.","in":"query","name":"limit","required":false,"schema":{"default":50000,"maximum":50000,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"format":"binary","type":"string"}}},"description":"XLSX file.","headers":{"X-Export-Limit":{"description":"Maximum number of rows returned by this export response.","schema":{"type":"integer"}},"X-Export-Offset":{"description":"Offset used for this export response.","schema":{"type":"integer"}},"X-Export-Truncated":{"description":"true when more rows are available and the client must call again with X-Next-Offset.","schema":{"type":"boolean"}},"X-Next-Offset":{"description":"Next offset when X-Export-Truncated is true.","schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid range or filter."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing or invalid X-API-Key."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Export usage sessions as Excel","tags":["Telemetry exports"]}},"/telemetry/utilization":{"get":{"description":"Hourly or daily utilization by fleet or asset. Uses precomputed aggregates when available, otherwise calculates the response during the request. Useful for BI, dashboards and customer reporting.","operationId":"getTelemetryUtilization","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Aggregation bucket. Hour and day buckets use precomputed aggregates when available.","in":"query","name":"bucket","required":false,"schema":{"default":"day","enum":["hour","day"],"type":"string"}},{"description":"Aggregate by one row per bucket for the whole scope, or one row per asset and bucket.","in":"query","name":"groupBy","required":false,"schema":{"default":"fleet","enum":["fleet","asset"],"type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Include buckets without activity. For groupBy=asset, large scopes require assetId or q to avoid enormous result sets.","in":"query","name":"includeZero","required":false,"schema":{"default":false,"type":"boolean"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryUtilizationResponse"}}},"description":"Hourly or daily utilization by fleet or asset. Uses precomputed aggregates when available, otherwise calculates the response during the request. Useful for BI, dashboards and customer reporting."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Get utilization metrics","tags":["Telemetry metrics"]}},"/telemetry/utilization/export.csv":{"get":{"description":"Paginated CSV export of utilization metrics.","operationId":"exportUtilizationCSV","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Aggregation bucket. Hour and day buckets use precomputed aggregates when available.","in":"query","name":"bucket","required":false,"schema":{"default":"day","enum":["hour","day"],"type":"string"}},{"description":"Aggregate by one row per bucket for the whole scope, or one row per asset and bucket.","in":"query","name":"groupBy","required":false,"schema":{"default":"fleet","enum":["fleet","asset"],"type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Export page size. Default and maximum 50000 rows.","in":"query","name":"limit","required":false,"schema":{"default":50000,"maximum":50000,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"text/csv":{"schema":{"format":"binary","type":"string"}}},"description":"CSV file.","headers":{"X-Export-Limit":{"description":"Maximum number of rows returned by this export response.","schema":{"type":"integer"}},"X-Export-Offset":{"description":"Offset used for this export response.","schema":{"type":"integer"}},"X-Export-Truncated":{"description":"true when more rows are available and the client must call again with X-Next-Offset.","schema":{"type":"boolean"}},"X-Next-Offset":{"description":"Next offset when X-Export-Truncated is true.","schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid range or filter."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing or invalid X-API-Key."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Export utilization as CSV","tags":["Telemetry exports"]}},"/telemetry/utilization/export.xlsx":{"get":{"description":"Paginated Excel export of utilization metrics.","operationId":"exportUtilizationXLSX","parameters":[{"description":"Range start. Date-only values are interpreted as UTC day start. Session endpoints use overlap semantics.","in":"query","name":"from","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Range end. Date-only values include the whole calendar day in current v1 behavior unless an RFC3339 timestamp is used.","in":"query","name":"to","required":false,"schema":{"description":"YYYY-MM-DD or RFC3339 UTC timestamp","type":"string"}},{"description":"Aggregation bucket. Hour and day buckets use precomputed aggregates when available.","in":"query","name":"bucket","required":false,"schema":{"default":"day","enum":["hour","day"],"type":"string"}},{"description":"Aggregate by one row per bucket for the whole scope, or one row per asset and bucket.","in":"query","name":"groupBy","required":false,"schema":{"default":"fleet","enum":["fleet","asset"],"type":"string"}},{"description":"Restrict the result to one asset UUID.","in":"query","name":"assetId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Case-insensitive search. Usually matches asset name, identifier, display code, telemetry device id, external reference or operator identifier depending on endpoint.","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"Export page size. Default and maximum 50000 rows.","in":"query","name":"limit","required":false,"schema":{"default":50000,"maximum":50000,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"format":"binary","type":"string"}}},"description":"XLSX file.","headers":{"X-Export-Limit":{"description":"Maximum number of rows returned by this export response.","schema":{"type":"integer"}},"X-Export-Offset":{"description":"Offset used for this export response.","schema":{"type":"integer"}},"X-Export-Truncated":{"description":"true when more rows are available and the client must call again with X-Next-Offset.","schema":{"type":"boolean"}},"X-Next-Offset":{"description":"Next offset when X-Export-Truncated is true.","schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid range or filter."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing or invalid X-API-Key."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"Export utilization as Excel","tags":["Telemetry exports"]}},"/webhooks/deliveries":{"get":{"description":"Lists recent webhook deliveries for monitoring and troubleshooting. Tenant API key only; customer-scoped keys receive 403.","operationId":"listWebhookDeliveries","parameters":[{"description":"Filter webhook deliveries by event name.","in":"query","name":"event","required":false,"schema":{"type":"string"}},{"description":"Webhook delivery status.","in":"query","name":"status","required":false,"schema":{"default":"all","enum":["all","pending","retrying","delivered","failed"],"type":"string"}},{"description":"Page size for JSON list responses. Default 100, maximum 500.","in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":500,"minimum":1,"type":"integer"}},{"description":"Zero-based result offset for pagination.","in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryListResponse"}}},"description":"Lists recent webhook deliveries for monitoring and troubleshooting. Tenant API key only; customer-scoped keys receive 403."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List webhook deliveries","tags":["Webhooks"]}},"/webhooks/events":{"get":{"description":"Webhook event catalog, delivery headers, signature format and retry policy for customer integrations.","operationId":"listWebhookEvents","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEventListResponse"}}},"description":"Webhook event catalog, delivery headers, signature format and retry policy for customer integrations."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List webhook events","tags":["Webhooks"]}},"/webhooks/subscriptions":{"get":{"description":"Lists configured tenant webhook subscriptions without exposing secrets. Tenant API key only; customer-scoped keys receive 403.","operationId":"listWebhookSubscriptions","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionListResponse"}}},"description":"Lists configured tenant webhook subscriptions without exposing secrets. Tenant API key only; customer-scoped keys receive 403."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid query parameter or request body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing, disabled or invalid X-API-Key."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"API key scope does not allow the requested object."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Object was not found in the current tenant/customerName scope."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Business rule conflict, invalid state transition or protected delete."},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request body or export is too large."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limit exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Server-side error."}},"security":[{"ApiKeyAuth":[]}],"summary":"List webhook subscriptions","tags":["Webhooks"]}}},"security":[{"ApiKeyAuth":[]}],"servers":[{"description":"Current installation","url":"https://api.sarkahq.com/api/external/v1"}],"tags":[{"description":"OpenAPI and human-readable API reference.","name":"Documentation"},{"description":"Key validation and scope discovery.","name":"Authentication"},{"description":"Assets, inspections, reports and reporting exports.","name":"Reporting"},{"description":"Asset types and inspection templates for customer portals, ERP mappings and integration UIs.","name":"Reporting reference data"},{"description":"Read-only telemetry state, sessions, data quality and alerts.","name":"Telemetry"},{"description":"Geofences, operators and other telemetry reference-data endpoints.","name":"Telemetry reference data"},{"description":"Hourly/daily utilization, container work and service request metrics. Uses gold aggregates where available.","name":"Telemetry metrics"},{"description":"CSV/XLSX exports with explicit paging headers.","name":"Telemetry exports"},{"description":"Create, read and update service requests.","name":"Service requests"},{"description":"Upload, list and download service request attachments.","name":"Service request files"},{"description":"Webhook event catalog, configured subscriptions and delivery monitoring.","name":"Webhooks"}]}