Connections / API reference

Available data

Discover which normalized fields the connection can provide.

GET/v1/connections/{id}/capabilities

Authentication: Bearer consumer API key with an explicit connection grant.

Preview contract. Availability depends on the deployed release, authorized connection and asset.

How to use this endpoint

Use fields such as odometer and engineHours to decide which features to show. Do not choose a different endpoint based on provider identity.
supported, conditional and unsupported describe adapter support. Conditional still depends on permissions, hardware and observations.
This describes support, not whether an individual asset has a fresh reading.
vehicleMetadata.fields describes each stored vehicle attribute; collection is off by default and requires the vehicleMetadata opt-in plus provider acceptance. Read the metadata endpoint for each asset's actual availability.

Parameters

Name	Where	Required	Type and behavior
`id`	path	Yes	`string`

Request example

bash

curl "$TELEMATICS_ORIGIN/v1/connections/$CONNECTION_ID/capabilities" \
  --header "Authorization: Bearer $TELEMATICS_CONSUMER_KEY"

Response fields

HTTP 200 returns Capabilities. Fields listed as required are guaranteed by this contract; optional fields may be absent.

Field	Type	Required
`id`	`string`	Yes
`adapterVersion`	`string`	Yes
`collection`	`native_feed \| poll`	No
`fields`	`object`	Yes
`faultModel`	`complete_snapshot \| explicit_records`	Yes
`authentication`	`string[]`	No
`limitations`	`string[]`	No
`vehicleMetadata`	`VehicleMetadataCapability`	Yes
`groupInventory`	`GroupInventoryCapability`	Yes

Nested field shapes and constraints are defined in the OpenAPI contract. For latest telemetry values, see normalized units and availability.

Response example

Synthetic values; this is a shape example, not a live customer response.

json

{
  "groupInventory": {
    "optInConfig": "groupInventory",
    "defaultEnabled": false,
    "selection": "explicit_approved_ids",
    "maxGroupIds": 100,
    "parentResolution": "approved_groups_only",
    "raw": "unsupported",
    "sourceTimestamps": "unsupported"
  },
  "id": "samsara",
  "adapterVersion": "1.5.0",
  "vehicleMetadata": {
    "optInConfig": "vehicleMetadata",
    "defaultEnabled": false,
    "fields": {
      "make": "conditional",
      "model": "conditional",
      "year": "conditional",
      "status": "conditional",
      "providerStatus": "unsupported",
      "fuelType": "unsupported",
      "sourceFuelType": "unsupported",
      "createdAt": "conditional",
      "updatedAt": "conditional",
      "licensePlate": "conditional",
      "licensePlateRegion": "unsupported",
      "serialNumber": "conditional",
      "groups": "conditional",
      "activeFrom": "unsupported",
      "activeTo": "unsupported"
    }
  },
  "collection": "native_feed",
  "fields": {
    "location": "conditional",
    "odometer": "conditional",
    "faults": "conditional",
    "engineHours": "conditional",
    "totalIdleTime": "conditional",
    "speed": "conditional",
    "heading": "conditional",
    "fuelPercent": "conditional",
    "batteryVoltage": "conditional",
    "engineState": "conditional"
  },
  "units": {
    "odometer": {
      "normalized": "meters",
      "source": [
        "meters"
      ],
      "selection": "obdOdometerMeters, then gpsOdometerMeters"
    },
    "engineRuntime": {
      "normalized": "seconds",
      "source": [
        "seconds"
      ],
      "status": "conditional; extendedTelemetry opt-in required"
    }
  },
  "faultModel": "complete_snapshot",
  "authentication": [
    "api_token",
    "oauth"
  ],
  "limitations": [
    "Requires vehicle/device telemetry and endpoint permissions",
    "Odometer may be engine or calibrated GPS derived",
    "US cloud API only in this adapter"
  ]
}

Errors and retries

HTTP status	Meaning
`401`	Consumer authentication denied
`404`	Resource missing or connection access denied
`503`	Service or database unavailable

Errors return {"error":"reason_code"}. Honor Retry-After when a 429 includes it. Permission and provider failures never become zero-valued telemetry. Connection health and reading status provide separate signals.

Response schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "adapterVersion": {
      "type": "string"
    },
    "collection": {
      "type": "string",
      "enum": [
        "native_feed",
        "poll"
      ]
    },
    "fields": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "enum": [
          "supported",
          "conditional",
          "unsupported"
        ]
      }
    },
    "faultModel": {
      "type": "string",
      "enum": [
        "complete_snapshot",
        "explicit_records"
      ]
    },
    "authentication": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "limitations": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "vehicleMetadata": {
      "$ref": "#/components/schemas/VehicleMetadataCapability"
    },
    "groupInventory": {
      "$ref": "#/components/schemas/GroupInventoryCapability"
    }
  },
  "required": [
    "id",
    "adapterVersion",
    "fields",
    "faultModel",
    "vehicleMetadata",
    "groupInventory"
  ]
}

← API overview · Download OpenAPI