Assets / API reference

Groups

Read stored group directories or approved groups and their parent relationships using one API.

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

• Add scope=directory to read all groups visible to the authorized provider account. This mode requires its own account-group consent and a current consent-bound API-key grant; existing vehicle and driver permissions do not authorize it. Scheduled directory refreshes require their own collection consent and enabled directory collection; vehicle-membership plans do not govern them. Awaiting separate rollout and fleet/provider acceptance.
• Omit scope for existing explicitly approved-ID group snapshots. Collection is off by default and needs approved group IDs, provider permissions and a separate rollout.
• Directory responses report sourceScope, capturedAt, fetchedAt, consistency and deletionEvidence. Exhausted pagination does not make provider enumeration transactional or prove access to hidden groups. An authorized directory may be pending or successfully empty; no grant returns 404.
• Directory IDs are stable per connection, verified provider account and source ID. They remain distinct from approved-ID group identities; directory driver and vehicle relationships resolve these shared IDs only under their current independent permissions. Use detail only with a directory ID and scope=directory. Group relationships must stay in their documented mode.
• Directory mode accepts timestamps with at most 40 characters and 6 fractional digits; approved-ID mode accepts at most 64 characters and higher fractional precision. Filters use exclusive stored modification times, not provider event times.
• Group requests run in a separate job. Successful snapshots poll at most hourly; supplier retries persist backoff, while permission/configuration failures pause that approved selection until reconnect or changed approvals. Core telemetry keeps its own schedule. Queue failures expose group_dispatch_unavailable independently; storage failures expose group_persistence_unavailable with transient backoff; malformed enabled selections pause before jobs or credentials.
• sourceId identifies the provider group. A parent is returned only within the authorized stored snapshot; expand=parent expands one level. Directory metadata.parentResolution distinguishes resolved, unresolved and root_or_unreported; an unknown external parent is not classified as a root.
• modifiedAfter/modifiedBefore filter our entity modification time, exclusively. Unchanged source records do not get a new modifiedAt on each poll. fetchedAt is snapshot persistence time; stale means older than 24 hours.
• Approving or removing a parent changes the child's resolved relationship and advances its modifiedAt, even when the provider's child payload stays unchanged.
• Use the next cursor with the same filters. A changed snapshot or approved scope expires cursors with 410. Errors in group collection preserve core telemetry and retain the last-good group snapshot when one exists, labeled degraded when configuration is valid. A first directory failure returns degraded with empty results and null capturedAt/fetchedAt; detail remains pending (409). Malformed enabled configuration returns 503 group_config_unavailable.
• Responses above 4 MiB return 413 group_response_too_large; lower limit or omit expand=parent and use parent references.
• Missing groups do not prove deletion. No tombstones or raw/user records are captured; raw=true and deleted=true return 409. Source created/updated times are unavailable in these mappings. This is partial Terminal parity.

Parameters

Request example

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

Response fields

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

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.

{
  "status": "available",
  "results": [
    {
      "id": "group_01D8ZQFGHVJ858NBF2Q7DV9MNC",
      "sourceId": "example-group",
      "provider": "samsara",
      "name": "Example group",
      "metadata": {
        "addedAt": "2026-10-01T00:00:00Z",
        "modifiedAt": "2026-10-01T00:00:00Z",
        "visibility": "visible"
      }
    }
  ],
  "fetchedAt": "2026-10-01T00:00:00Z",
  "errorCode": null,
  "retrieval": "stored"
}

Errors and retries

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.

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/GroupInventoryResponse"
    },
    {
      "$ref": "#/components/schemas/GroupDirectoryResponse"
    }
  ]
}

← API overview · Download OpenAPI