Synchronization / API reference

Request a sync

Manage durable sync work through one API with application and connection authorization.

Authentication: Bearer application secret and Connection-Token, with an explicit operation grant.

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

How to use this endpoint

• Review-only, default off and pending deployment/acceptance. Send the server-side application secret in Authorization and the application-scoped connection credential in Connection-Token. The legacy pt_ consumer key does not authorize these routes. Each operation rechecks current credentials and its operation grant inside the database transaction.
• An operator must configure the complete required purpose set and separately approve each selection/account/history scope. This increment supports vehicles, vehicle group memberships and trips for that explicitly approved selection. It does not discover the whole fleet or synchronize every Terminal model. Unsupported required work is rejected atomically, rather than omitted.
• POST /v1/syncs returns 201. Its optional body accepts startFrom or fractional days and providerRequests; combining selectors is refused pending precedence validation. Nonempty providerRequests workflows are not implemented and return 409. The first default starts now; later defaults start at the previous requestedAt. A trip-only empty interval is refused. Request/retry need unified collection and every configured purpose flag enabled; reads/cancel remain available when worker collection is paused.
• Retry only a failed job, with an empty body. It preserves the original request, interval, selection and purpose authority, increments attempts and requires fresh receipts. Cancel only requested/in_progress work, with an empty body. Both controls return id/message; non-actionable state returns 422. Cancellation never counts as completion or prematurely releases an in-flight supplier lease.
• Completion and 100% progress require committed data receipts for every admitted unit. Queue acceptance is not data completion. Interrupted delivery is retried at least once, with stale attempt and physical-owner checks. No exact freshness promise is implied by the five-minute default scheduler window.
• List uses limit 1–100 (default 25), newest requestedAt then ID, optional status, and expand=issues. Feed next back as cursor with unchanged filters. Cursors expire after 15 minutes or credential/grant changes. The upper creation horizon is fixed; status is live, so changing status may alter filtered results. Only this application's public syncs are visible; private/internal jobs are excluded. Issues are empty in this increment; provider issue expansion and workflows remain pending.
• Plans exceeding 10,000 units or 4 MiB are rejected without truncating approved work. Response and scheduling limits are service controls pending comparative acceptance. Lost successful POST responses require history/status reconciliation before retrying; public request idempotency is not yet offered.

Parameters

No JSON request body is required.

Request example

curl --request POST "$TELEMATICS_ORIGIN/v1/syncs" \
  --header "Authorization: Bearer $TELEMATICS_APPLICATION_SECRET" \
  --header "Connection-Token: $TELEMATICS_CONNECTION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"days":0.5}'

Response fields

HTTP 201 returns Sync. 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.

{
  "id": "sync_01K6Z5NHHKST68MFFEXS0PQ91Q",
  "status": "requested",
  "requestedAt": "2026-10-01T00:00:00Z",
  "startFrom": "2026-10-01T00:00:00Z",
  "attempts": 1,
  "progress": 0,
  "issues": [],
  "providerRequests": []
}

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.

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "status",
    "requestedAt"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^sync_[0-9A-HJKMNP-TV-Z]{26}$"
    },
    "status": {
      "type": "string",
      "enum": [
        "requested",
        "in_progress",
        "completed",
        "failed"
      ]
    },
    "requestedAt": {
      "type": "string",
      "format": "date-time"
    },
    "startFrom": {
      "type": "string",
      "format": "date-time"
    },
    "completedAt": {
      "type": "string",
      "format": "date-time"
    },
    "attempts": {
      "type": "integer",
      "minimum": 1
    },
    "progress": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "failureReason": {
      "type": "string"
    },
    "issues": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 0,
      "description": "Empty in this increment; expanded provider issues remain pending implementation."
    },
    "providerRequests": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "historical_files",
          "provision_credentials"
        ]
      },
      "maxItems": 0,
      "description": "Nonempty supplier workflows are rejected at admission in this increment."
    }
  }
}

← API overview · Download OpenAPI