Assets / API reference

List assets

List core assets or normalized account-bound vehicle profiles.

GET/v1/connections/{id}/vehicles

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

Default core asset mode returns up to 100 assets; pass nextCursor as after. scope=directory selects normalized profiles, results/next pagination and separate profile consent/read grants.
Directory profiles share vcl IDs with trips, support exclusive modifiedAfter/Before and current hidden filtering. Stored reads make no upstream call. Membership refresh cadence belongs to an independently approved collection plan; capture/fetch timestamps and health describe actual evidence, not an exact refresh-time promise. Groups use shared directory IDs with current separate profile/membership/directory grants; expand=groups returns stored objects. groupMembership makes missing, partial, stale or degraded evidence explicit.
Profile filters are configured through an operator-only consent/generation-checked RPC; public filter management and ingestion filtering remain pending.
In default core mode, use each provider_id as vehicleId in this connection's telemetry, fault and usage endpoints. Profile detail and trip vehicleIds filters instead use normalized vcl_ IDs returned by scope=directory. Treat it as an opaque identifier; do not build upstream-provider URLs from it.
Asset IDs are scoped to the connection. Store connection ID and asset ID together.

Parameters

Name	Where	Required	Type and behavior
`id`	path	Yes	`string`
`after`	query	No	`string` Opaque provider vehicle ID from nextCursor. Keep the same time window when paging.
`scope`	query	No	`directory` directory selects independently authorized account-bound normalized profiles; omitted on lists retains core assets
`limit`	query	No	`integer` Stored normalized profiles only; no provider call Default: `100`
`cursor`	query	No	`string` Opaque key/permission/publication/revision/filter-bound cursor; restart after 410
`modifiedAfter`	query	No	`string` Exclusive service-observed change bound, including conservative permission/relationship changes; not upstream update time
`modifiedBefore`	query	No	`string` Exclusive service-observed change bound, including conservative permission/relationship changes; not upstream update time
`hidden`	query	No	`boolean` Include authorized profiles hidden by current configured include/exclude/status filters; does not grant new access Default: `false`
`raw`	query	No	`boolean` Requested true raw/deleted returns409 until independently implemented and authorized Default: `false`
`deleted`	query	No	`boolean` Requested true raw/deleted returns409 until independently implemented and authorized Default: `false`
`expand`	query	No	`groups \| devices \| groups,devices \| devices,groups` groups resolves stored normalized group objects under current profile/membership/directory grants; unavailable relationship access or device expansion returns409

Request example

bash

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

Response fields

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

Vehicles

Field	Type	Required
`vehicles`	`Vehicle[]`	Yes
`nextCursor`	`string \| null`	Yes

VehicleProfilePage

Field	Type	Required
`status`	`pending \| available \| degraded`	Yes
`retrieval`	`"stored"`	Yes
`results`	`VehicleEntity[]`	Yes
`next`	`string`	No
`publishedAt`	`string \| null`	Yes
`errorCode`	`string \| null`	Yes
`selection`	`"approved_source_vehicle_ids"`	Yes
`completeness`	`"not_established"`	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

{
  "vehicles": [
    {
      "provider_id": "asset-001",
      "name": "Example asset",
      "vin": null
    }
  ],
  "nextCursor": null
}

Errors and retries

HTTP status	Meaning
`400`	Invalid directory query or cursor
`401`	Consumer authentication denied
`404`	Resource missing or connection access denied
`409`	Profile detail pending, raw/deletion/group/device expansion unavailable
`410`	Permission/publication/filter cursor expired
`413`	Profile response exceeds4MiB; lower list limit
`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

{
  "oneOf": [
    {
      "$ref": "#/components/schemas/Vehicles"
    },
    {
      "$ref": "#/components/schemas/VehicleProfilePage"
    }
  ]
}

← API overview · Download OpenAPI