Data catalog

curl "$TELEMATICS_ORIGIN/v1/catalog"

{
  "apiVersion": "v1",
  "catalogVersion": "1.15.0",
  "releaseStatus": "Preview contract; availability depends on the deployed environment and authorized connection. Extended telemetry, vehicle metadata and groups require explicit opt-in and provider validation",
  "reviewedAt": "2026-10-10",
  "fields": [
    {
      "name": "location",
      "label": "Location",
      "unit": "degrees",
      "kind": "position",
      "freshnessSeconds": 900,
      "valueKey": "latitude,longitude",
      "availability": "Check connection capabilities and each reading's status; absence is unknown, never zero"
    },
    {
      "name": "odometer",
      "label": "Odometer",
      "unit": "meters",
      "kind": "counter",
      "freshnessSeconds": 129600,
      "valueKey": "meters",
      "availability": "Check connection capabilities and each reading's status; absence is unknown, never zero"
    },
    {
      "name": "engineHours",
      "label": "Lifetime engine runtime",
      "unit": "seconds",
      "kind": "counter",
      "freshnessSeconds": 129600,
      "valueKey": "seconds",
      "availability": "Check connection capabilities and each reading's status; absence is unknown, never zero"
    },
    {
      "name": "totalIdleTime",
      "label": "Lifetime idle duration",
      "unit": "seconds",
      "kind": "counter",
      "freshnessSeconds": 129600,
      "valueKey": "seconds",
      "availability": "Check connection capabilities and each reading's status; absence is unknown, never zero"
    },
    {
      "name": "speed",
      "label": "Speed",
      "unit": "meters_per_second",
      "kind": "gauge",
      "freshnessSeconds": 900,
      "valueKey": "value",
      "availability": "Check connection capabilities and each reading's status; absence is unknown, never zero"
    },
    {
      "name": "heading",
      "label": "Heading",
      "unit": "degrees",
      "kind": "gauge",
      "freshnessSeconds": 900,
      "valueKey": "value",
      "availability": "Check connection capabilities and each reading's status; absence is unknown, never zero"
    },
    {
      "name": "fuelPercent",
      "label": "Fuel level",
      "unit": "percent",
      "kind": "gauge",
      "freshnessSeconds": 900,
      "valueKey": "value",
      "availability": "Check connection capabilities and each reading's status; absence is unknown, never zero"
    },
    {
      "name": "batteryVoltage",
      "label": "Vehicle battery voltage",
      "unit": "volts",
      "kind": "gauge",
      "freshnessSeconds": 900,
      "valueKey": "value",
      "availability": "Check connection capabilities and each reading's status; absence is unknown, never zero"
    },
    {
      "name": "engineState",
      "label": "Engine state",
      "unit": "enum",
      "kind": "state",
      "freshnessSeconds": 900,
      "valueKey": "state",
      "availability": "Check connection capabilities and each reading's status; absence is unknown, never zero"
    }
  ],
  "faults": {
    "model": "Occurrences and opened/cleared events; separate from numeric history",
    "absence": "Missing diagnostics never imply clearance"
  },
  "endpoints": [
    {
      "method": "POST",
      "path": "/v1/syncs",
      "summary": "Request a sync of the complete configured approved selection",
      "auth": true,
      "schema": "Sync",
      "parameters": []
    },
    {
      "method": "GET",
      "path": "/v1/syncs",
      "summary": "List this application's sync history for the authorized connection",
      "auth": true,
      "schema": "SyncPage",
      "parameters": [
        "limit",
        "cursor",
        "status",
        "expand"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/syncs/{id}",
      "summary": "Read sync progress and committed completion",
      "auth": true,
      "schema": "Sync",
      "parameters": [
        "expand"
      ]
    },
    {
      "method": "POST",
      "path": "/v1/syncs/{id}/retry",
      "summary": "Retry the original frozen sync plan with fresh ownership",
      "auth": true,
      "schema": "SyncControl",
      "parameters": []
    },
    {
      "method": "POST",
      "path": "/v1/syncs/{id}/cancel",
      "summary": "Cancel logical work without prematurely freeing supplier capacity",
      "auth": true,
      "schema": "SyncControl",
      "parameters": []
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/trips",
      "summary": "Stored completed trips with normalized references and explicit units",
      "auth": true,
      "schema": "TripPage",
      "parameters": [
        "limit",
        "cursor",
        "modifiedAfter",
        "modifiedBefore",
        "startedAfter",
        "startedBefore",
        "endedAfter",
        "endedBefore",
        "vehicleIds",
        "driverIds",
        "expand",
        "raw",
        "deleted"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/trips/{tripId}",
      "summary": "Read one authorized stored trip",
      "auth": true,
      "schema": "Trip",
      "parameters": [
        "expand",
        "raw",
        "deleted"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/drivers",
      "summary": "Stored driver directory with separate consent and read access",
      "auth": true,
      "schema": "DriverDirectory",
      "parameters": [
        "limit",
        "cursor",
        "modifiedAfter",
        "modifiedBefore",
        "raw",
        "deleted",
        "expand",
        "groupScope"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/groups",
      "summary": "Stored group directories or approved groups with parent relationships",
      "auth": true,
      "schema": "GroupReadResponse",
      "parameters": [
        "scope",
        "limit",
        "cursor",
        "expand",
        "modifiedAfter",
        "modifiedBefore",
        "deleted",
        "raw"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/groups/{groupId}",
      "summary": "Read one stored directory group by stable normalized ID",
      "auth": true,
      "schema": "GroupDirectoryResult",
      "parameters": [
        "scope",
        "raw",
        "expand"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/drivers/{driverId}",
      "summary": "Read one stored driver by stable normalized ID",
      "auth": true,
      "schema": "DriverResult",
      "parameters": [
        "raw",
        "expand",
        "groupScope"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/vehicles/{vehicleId}/metadata",
      "summary": "Stored provider vehicle identity, status and group references",
      "auth": true,
      "schema": "VehicleMetadataResponse",
      "parameters": []
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/vehicles/{vehicleId}/profile",
      "summary": "Cached vehicle identity, images, specifications and factory build",
      "auth": true,
      "schema": "VehicleProfile",
      "parameters": []
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/vehicles/{vehicleId}/identity",
      "summary": "Cached vehicle identity with source and availability",
      "auth": true,
      "schema": "IdentitySection",
      "parameters": []
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/vehicles/{vehicleId}/images",
      "summary": "Cached vehicle images with source and availability",
      "auth": true,
      "schema": "ImagesSection",
      "parameters": []
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/vehicles/{vehicleId}/specifications",
      "summary": "Cached vehicle specifications with source and availability",
      "auth": true,
      "schema": "SpecificationsSection",
      "parameters": []
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/vehicles/{vehicleId}/build",
      "summary": "Cached vehicle build with source and availability",
      "auth": true,
      "schema": "BuildSection",
      "parameters": []
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/locations",
      "summary": "Stored fleet locations with per-asset freshness, 100 per page",
      "auth": true,
      "schema": "FleetLocations",
      "parameters": [
        "after"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/catalog",
      "summary": "Normalized fields, units and API operations",
      "auth": false,
      "schema": "Catalog",
      "parameters": []
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}",
      "summary": "Connection identity and collection health",
      "auth": true,
      "schema": "Connection",
      "parameters": []
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/capabilities",
      "summary": "Provider capabilities and adapter version",
      "auth": true,
      "schema": "Capabilities",
      "parameters": []
    },
    {
      "method": "POST",
      "path": "/v1/connections/{id}/connect-sessions",
      "summary": "Create a ten-minute provider consent link",
      "auth": true,
      "schema": "ConnectSession",
      "parameters": []
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/connect-sessions/{sessionId}",
      "summary": "Read the initiating consumer's session status",
      "auth": true,
      "schema": "SessionStatus",
      "parameters": []
    },
    {
      "method": "POST",
      "path": "/v1/connections/{id}/disconnect",
      "summary": "Disable local access and collection",
      "auth": true,
      "schema": "Disconnect",
      "parameters": []
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/vehicles",
      "summary": "List core assets or independently authorized normalized vehicle profiles",
      "auth": true,
      "schema": "VehicleReadResponse",
      "parameters": [
        "after",
        "scope",
        "limit",
        "cursor",
        "modifiedAfter",
        "modifiedBefore",
        "hidden",
        "raw",
        "deleted",
        "expand"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/vehicles/{vehicleId}",
      "summary": "Read one current authorized normalized vehicle profile",
      "auth": true,
      "schema": "VehicleEntity",
      "parameters": [
        "scope",
        "hidden",
        "raw",
        "deleted",
        "expand"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/vehicles/{vehicleId}/telemetry",
      "summary": "Latest readings with source, time and freshness",
      "auth": true,
      "schema": "Telemetry",
      "parameters": []
    },
    {
      "method": "POST",
      "path": "/v1/connections/{id}/vehicles/{vehicleId}/refresh",
      "summary": "Fetch latest provider readings; return a labeled fallback on failure",
      "auth": true,
      "schema": "Telemetry",
      "parameters": []
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/faults",
      "summary": "Active fault occurrences, 100 per page",
      "auth": true,
      "schema": "Faults",
      "parameters": [
        "after"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/fault-events",
      "summary": "Opened/cleared events with durable cursor",
      "auth": true,
      "schema": "FaultEvents",
      "parameters": [
        "after"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/vehicles/{vehicleId}/history",
      "summary": "Stored readings, 100 per page; up to 31 days per query",
      "auth": true,
      "schema": "History",
      "parameters": [
        "startTime",
        "endTime",
        "after",
        "metric"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/vehicles/{vehicleId}/utilization",
      "summary": "Observed engine runtime versus not running, distance and idle time; up to 7 days",
      "auth": true,
      "schema": "Utilization",
      "parameters": [
        "startTime",
        "endTime"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/vehicles/{vehicleId}/distance",
      "summary": "Distance accumulated across valid odometer intervals",
      "auth": true,
      "schema": "CounterReport",
      "parameters": [
        "startTime",
        "endTime"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/vehicles/{vehicleId}/engine-hours",
      "summary": "Engine runtime accumulated across valid counter intervals",
      "auth": true,
      "schema": "CounterReport",
      "parameters": [
        "startTime",
        "endTime"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/vehicles/{vehicleId}/idling",
      "summary": "Idle duration from supported cumulative counters",
      "auth": true,
      "schema": "CounterReport",
      "parameters": [
        "startTime",
        "endTime"
      ]
    },
    {
      "method": "GET",
      "path": "/v1/connections/{id}/utilization",
      "summary": "Per-vehicle fleet summaries, 10 vehicles per page; up to 7 days",
      "auth": true,
      "schema": "FleetUtilization",
      "parameters": [
        "startTime",
        "endTime",
        "after"
      ]
    }
  ],
  "enrichment": {
    "releaseStatus": "implementation_pending_rollout",
    "products": [
      "identity",
      "images",
      "specifications",
      "build"
    ],
    "collection": "Automatically queued on new valid VIN discovery; cached GETs never make supplier calls",
    "enablement": "Per-connection opt-in; specifications and build require separate product entitlement",
    "measurements": "Specifications retain provider text including reported units; telemetry stays meters and seconds",
    "images": "Each image has a kind; listing photos do not establish current condition or configuration"
  },
  "driverDirectory": {
    "releaseStatus": "implementation_pending_rollout",
    "authorization": "Separate driver-directory consent and consumer read grant; vehicle access does not grant driver PII",
    "retrieval": "Stored reads only; GET never calls a provider",
    "identity": "Stable drv_ ULID per connection, bound account and source driver",
    "modification": "Ingestion change time with microsecond precision; driver capture alone does not advance it. Approved group/config/health and directory group consent/publication/health changes advance a conservative shared relationship clock for all current drivers",
    "membershipCapture": "groupMembership.sourceScope distinguishes credential-visible source memberships from an explicitly approved source-group selection. Known-empty groups applies only to that scope; a changed selection omits groups until recapture",
    "groupRelations": "By default groups contains approved normalized IDs. groupScope=directory requires both current read grants and matching verified accounts; references/expand=groups use the same IDs/objects as groups?scope=directory. Unknown membership omits groups; missing directory references remain partial",
    "gaps": [
      "Full source group coverage and provider membership acceptance",
      "Physical deletion and raw data",
      "Source-clock replication",
      "Full Terminal token authorization",
      "Large-account enumeration",
      "Actual fleet/provider acceptance"
    ]
  },
  "tripHistory": {
    "releaseStatus": "implemented_connection_activation_required",
    "retrieval": "stored",
    "authorization": "Independent trip-purpose consent and current read grant; driver relationships additionally require matching current driver consent, snapshot and read grant",
    "units": {
      "distance": "kilometers",
      "duration": "milliseconds"
    },
    "maxPageSize": 100,
    "maxFilterIds": 50,
    "responseByteLimit": 4194304,
    "coverage": "Committed work units, including repeated windows; no fleet-wide completeness or freshness promise",
    "gaps": [
      "Original raw/deletion/retention rights",
      "Full account-wide sync planning and remaining data domains",
      "Automatic dense-unit sizing and complete source correction/coverage",
      "Provider/fleet acceptance"
    ]
  },
  "groupInventory": {
    "optInConfig": "groupInventory",
    "defaultEnabled": false,
    "selection": "explicit_approved_ids",
    "maxGroupIds": 100,
    "parentResolution": "approved_groups_only",
    "raw": "unsupported",
    "sourceTimestamps": "unsupported"
  },
  "groupDirectory": {
    "releaseStatus": "implementation_pending_rollout",
    "enablement": "Separate account-group consent and consent-bound read grant; no automatic collection is connected",
    "query": "scope=directory on list or detail; omitting scope on lists retains approved-ID behavior",
    "identity": "Stable group_ ID per connection, verified account and source ID; directory and approved-ID identities are not yet unified",
    "consistency": "not_transactional",
    "deletionEvidence": "none",
    "maxRows": 50000,
    "maxReferences": 100000,
    "projectedByteLimit": 67108864,
    "responseByteLimit": 4194304,
    "pagination": "Stored ID order; snapshot, consent, generation and filters bind the cursor; changed publication returns 410",
    "relations": "One-level parent expansion within the authorized snapshot; unresolved parent remains explicit. Driver and vehicle relationships retain approved-ID snapshots or source references",
    "gaps": [
      "Raw records and physical deletion",
      "Cross-mode IDs and driver relationship unification",
      "Large-account and provider/fleet acceptance",
      "Hosted consent and automatic scheduling"
    ]
  },
  "vehicleProfiles": {
    "releaseStatus": "implemented_connection_activation_required",
    "retrieval": "stored",
    "authorization": "Separate current profile-purpose approval and read grant",
    "selection": "approved_source_vehicle_ids",
    "query": "scope=directory; stable normalized vcl IDs shared with trips",
    "maxPageSize": 100,
    "responseByteLimit": 4194304,
    "visibility": "Current includeIds overrides excludeIds/status; hidden=true returns only independently authorized stored profiles",
    "groupRelationships": "IDs and expand=groups require current profile, membership and directory read grants with matching verified account in one SQL snapshot; trip expand=vehicle includes these same IDs and availability without nested group objects; availability distinguishes available/not_authorized/pending/missing/invalid/partial/stale/degraded; reported source coverage is credential-visible, not full-fleet",
    "gaps": [
      "Device relations, raw and physical deletion",
      "Public filter management and ingestion filtering",
      "Full sync and every-domain supplier quotas",
      "Hosted/provider/fleet acceptance"
    ]
  },
  "vehicleMetadata": {
    "releaseStatus": "implementation_pending_rollout",
    "fields": [
      "make",
      "model",
      "year",
      "status",
      "providerStatus",
      "fuelType",
      "sourceFuelType",
      "createdAt",
      "updatedAt",
      "licensePlate",
      "licensePlateRegion",
      "serialNumber",
      "groups",
      "activeFrom",
      "activeTo"
    ],
    "enablement": "Per-connection vehicleMetadata literal true; disabled by default",
    "availability": "Each field is available, missing, unsupported or invalid; check the stored snapshot's status and fetchedAt",
    "interpretation": "Provider vehicle metadata is distinct from VIN enrichment, telemetry and dispatch availability; group references are not a complete group directory"
  },
  "roadmap": [
    {
      "area": "Provider utilization and fuel reports",
      "status": "documented_not_implemented",
      "use": "Driving/idle fuel, driving duration, native utilization scores; retain each provider's timezone and definition"
    },
    {
      "area": "Trips and location backfill",
      "status": "documented_not_implemented",
      "use": "Earlier history, trip reconstruction and route activity"
    },
    {
      "area": "Fuel consumption and efficiency",
      "status": "documented_not_implemented",
      "use": "Fuel volume, fuel per distance and filtered reports"
    },
    {
      "area": "EV telemetry",
      "status": "documented_not_implemented",
      "use": "Charge percentage/status, battery health, energy consumed and charging"
    },
    {
      "area": "Engine health and PTO",
      "status": "documented_not_implemented",
      "use": "RPM, coolant temperature, oil pressure, DEF and configured auxiliary/PTO inputs"
    },
    {
      "area": "Inspections, drivers, safety and compliance",
      "status": "access_review_required",
      "use": "Separate product modules beyond vehicle telemetry"
    }
  ],
  "limits": {
    "historyDaysPerRequest": 31,
    "utilizationDaysPerRequest": 7,
    "historyPageSize": 100,
    "fleetUtilizationPageSize": 10,
    "utilizationMaxReadingsPerVehicle": 10000
  }
}