> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catenatelematics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# v2.0.0 - First Stable Release

> Major API improvements and standardization

**Released 2nd December 2025**

This is the first stable release of the Telematics API v2. This release focuses on consistent filtering, clearer parameter names, richer error responses, and reorganized endpoints across the Telematics API.

<Check>
  **Stable Release:** This version represents a stable, production-ready API with commitment to backward compatibility within v2.x releases going forward.
</Check>

## Endpoint Changes

<AccordionGroup>
  <Accordion title="Reference Data Endpoints Renamed" icon="book">
    **Removed:**

    * `/v2/telematics/refs/*` (all reference data endpoints)

    **Added:**

    * `/v2/telematics/ref-hos-rulesets`
    * `/v2/telematics/ref-hos-event-codes`
    * `/v2/telematics/ref-hos-malfunction-codes`
    * `/v2/telematics/ref-hos-regions`
    * `/v2/telematics/ref-timezones`

    **Migration:** Update all reference data calls to use the new `ref-*` pattern instead of `refs/*`.
  </Accordion>

  <Accordion title="Vehicle Locations Redesigned" icon="location-dot">
    **Removed:**

    * `/v2/telematics/latest_locations` - Get latest locations for all vehicles
    * `/v2/telematics/vehicles/{vehicle_id}/locations` - Get location history for one vehicle

    **Added:**

    * `/v2/telematics/vehicle-locations` - Unified endpoint with `only_latest` parameter (defaults to `true`)

    **Migration:**

    ```bash theme={null}
    # Before (latest locations)
    GET /v2/telematics/latest_locations

    # After
    GET /v2/telematics/vehicle-locations?only_latest=true

    # Before (history for one vehicle)
    GET /v2/telematics/vehicles/{vehicle_id}/locations?start_date=...&end_date=...

    # After
    GET /v2/telematics/vehicle-locations?vehicle_ids={vehicle_id}&only_latest=false&from_datetime=...&to_datetime=...
    ```
  </Accordion>

  <Accordion title="Vehicle Sensors Reorganized" icon="gauge">
    **Removed:**

    * `/v2/telematics/vehicle-sensors` - List all sensor readings
    * `/v2/telematics/vehicle-sensors/{vehicle_sensor_id}` - Get sensor by ID

    **Added:**

    * `/v2/telematics/vehicle-sensor-events` - List sensor events with filtering
    * `/v2/telematics/vehicles/{vehicle_id}/sensor-events` - Get sensor events for specific vehicle

    **Migration:** Use the new sensor events endpoints with time-based filtering instead of accessing individual sensor readings by ID.
  </Accordion>

  <Accordion title="DVIR Endpoints Updated" icon="clipboard-list">
    **Removed:**

    * `/v2/telematics/dvir-logs/{dvir_log_id}` - Get single DVIR log by ID

    **Still Available:**

    * `/v2/telematics/dvir-logs` - List DVIR logs
    * `/v2/telematics/dvir-logs/{dvir_log_id}/defects` - Get defects for a specific log

    **Added:**

    * `/v2/telematics/dvir-defects` - List all defects across DVIR logs

    **Migration:** Use the list endpoint with filtering instead of fetching individual DVIR logs by ID.
  </Accordion>

  <Accordion title="HOS Annotations Embedded" icon="note-sticky">
    **Removed:**

    * `/v2/telematics/hos-events/{hos_event_id}/annotations` - Standalone annotations endpoint

    **New Behavior:**

    * Annotations are now included directly in the `hos_event` payload via an `annotations` field

    **Migration:**

    ```json theme={null}
    // Before: Separate API call
    GET /v2/telematics/hos-events/{id}/annotations

    // After: Included in event response
    GET /v2/telematics/hos-events/{id}
    {
      "hos_event_id": "evt_123",
      "annotations": [
        {
          "created_at": "2025-12-01T10:30:00Z",
          "remarks": "Driver added manual note"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## Query Parameter Changes

All list endpoints now use standardized parameter naming:

| Old Parameter | New Parameter | Change Description |
| - | - | - |
| `source_data` | `include_source_data` | Renamed for clarity (boolean flag) |
| `driver_id` | `driver_ids` | Now accepts multiple IDs (array, max 100) |
| `vehicle_id` | `vehicle_ids` | Now accepts multiple IDs (array, max 100) |
| `start_date` / `end_date` | `from_datetime` / `to_datetime` | Standardized time filtering (ISO 8601 UTC) |

**New Fleet Scoping Filters:**

* `fleet_ids` - Filter by Catena fleet UUIDs (array)
* `fleet_refs` - Filter by your internal fleet references (array)

**Migration Example:**

```bash theme={null}
# Before
GET /v2/telematics/trips?fleet_id=fleet_123&driver_id=driver_456&start_date=2025-11-01&end_date=2025-11-10&source_data=true

# After
GET /v2/telematics/trips?fleet_ids=fleet_123&driver_ids=driver_456&from_datetime=2025-11-01T00:00:00Z&to_datetime=2025-11-10T23:59:59Z&include_source_data=true
```

## Time Filtering Standardization

<CardGroup cols={2}>
  <Card title="Before" icon="calendar-xmark">
    Inconsistent parameter names:

    * `start_date` / `end_date`
    * Hard-coded defaults in spec
    * Varying time formats
  </Card>

  <Card title="After" icon="calendar-check">
    Standardized across all endpoints:

    * `from_datetime` / `to_datetime`
    * ISO 8601 UTC format required
    * Documented defaults (e.g., "now() - 1 day")
    * Time window limits (commonly 15 days max)
  </Card>
</CardGroup>

<Warning>
  **Time Window Limits:** Most endpoints now enforce maximum time ranges (typically 15 days). Requests exceeding this limit will return a `422 Unprocessable Entity` error.
</Warning>

## Error Response Changes

Error handling has been standardized across all endpoints:

**New Status Codes:**

* `400 Bad Request` - Invalid parameters or malformed requests
* `401 Unauthorized` - Missing or invalid authentication
* `403 Forbidden` - Insufficient permissions
* `404 Not Found` - Resource doesn't exist
* `422 Unprocessable Entity` - Validation errors (new schema)
* `429 Too Many Requests` - Rate limit exceeded
* `500 Internal Server Error` - Server-side errors

**Deprecated Parameter Errors:**

```json theme={null}
{
  "error": "deprecated_parameter",
  "message": "The parameter 'fleet_id' has been removed. Use 'fleet_ids' instead.",
  "status_code": 400
}
```

**Deprecated Endpoint Errors:**

```json theme={null}
{
  "error": "endpoint_removed",
  "message": "The /annotations endpoint has been removed. Use the 'annotations' field on the hos_event resource instead.",
  "status_code": 410
}
```

<Tip>
  Update your error handling logic to parse the new error schema and handle the expanded set of status codes.
</Tip>

## New Features

<AccordionGroup>
  <Accordion title="HOS Daily Summaries" icon="calendar-day">
    New endpoint for aggregated daily Hours of Service data:

    ```bash theme={null}
    GET /v2/telematics/hos-daily-summaries
    ```

    Returns daily rollups of driving time, on-duty hours, violations, and remaining available hours per driver.
  </Accordion>

  <Accordion title="DVIR Defects Listing" icon="list-check">
    New endpoint to list all DVIR defects across multiple logs:

    ```bash theme={null}
    GET /v2/telematics/dvir-defects?from_datetime=...&to_datetime=...
    ```

    Allows filtering defects without needing to query individual DVIR logs.
  </Accordion>

  <Accordion title="Enhanced Fleet Scoping" icon="filter">
    All list endpoints now support:

    * `fleet_ids` - Filter by Catena's internal fleet UUIDs
    * `fleet_refs` - Filter by your internal fleet identifiers

    This enables multi-fleet queries and better isolation of fleet data.
  </Accordion>

  <Accordion title="Plural ID Filtering" icon="list">
    Most endpoints now accept arrays of IDs for efficient batch filtering:

    * `driver_ids` (max 100)
    * `vehicle_ids` (max 100)
    * `fleet_ids` (max 100)
    * `fleet_refs` (max 100)

    Reduces the need for multiple API calls when querying data for multiple entities.
  </Accordion>
</AccordionGroup>

## Migration Checklist

<Steps>
  <Step title="Update Query Parameters">
    * Rename `source_data` → `include_source_data`
    * Convert singular ID params to plural arrays: `driver_id` → `driver_ids`, `vehicle_id` → `vehicle_ids`
    * Replace `start_date`/`end_date` with `from_datetime`/`to_datetime` (ISO 8601 UTC)
    * Add fleet scoping filters where needed: `fleet_ids` or `fleet_refs`
  </Step>

  <Step title="Update Endpoint Paths">
    * Reference data: `/refs/*` → `/ref-*`
    * Vehicle locations: Use unified `/vehicle-locations` with `only_latest` parameter
    * Vehicle sensors: Use `/vehicle-sensor-events` or `/vehicles/{id}/sensor-events`
    * Remove calls to deleted endpoints (single DVIR log by ID, HOS annotations)
  </Step>

  <Step title="Update Error Handling">
    * Handle new status codes: 400, 401, 403, 404, 422, 429, 500
    * Parse new error response schema
    * Handle deprecated parameter/endpoint errors gracefully
  </Step>

  <Step title="Test Time Window Limits">
    * Verify your queries respect the 15-day maximum time range
    * Implement pagination for longer historical queries
    * Handle `422` errors when time range is too large
  </Step>

  <Step title="Update Client Libraries">
    * Regenerate API clients from the new OpenAPI spec
    * Update hardcoded endpoint URLs
    * Test all integration points with the new API structure
  </Step>
</Steps>

***

## Need Help?

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/telematics-api">
    View complete endpoint documentation with the new parameter structure
  </Card>

  <Card title="Contact Support" icon="life-ring" href="mailto:support@catenaclearing.io">
    Questions about migrating your integration? Our team is here to help
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.