Pagination & Response Envelope

All endpoints in the API follow a consistent response envelope. List endpoints support offset-based pagination.

Response Envelope

Every response — success or error — is wrapped in a standard envelope. This makes it safe to always check success first before accessing data.

List endpoints

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "total": 150,
    "limit": 25,
    "offset": 0
  }
}

Field	Type	Description
success	boolean	true when the request completed without errors
data	array	The matching resources for this page
meta.total	integer	Total records matching the query after filters, before pagination
meta.limit	integer	Number of records returned in this page
meta.offset	integer	Number of records skipped (starting position)

Single-resource endpoints

GET-by-ID endpoints return data as an object, not an array. The meta field may be empty or omitted:

{
  "success": true,
  "data": {
    "id": "104820579301",
    "name": "Truck-42",
    "plate": "ABC-1234",
    "status": "A"
  },
  "meta": {}
}

Write operations (POST / PUT)

Create and update endpoints return the created or updated resource in data:

{
  "success": true,
  "data": {
    "id": "104820579305",
    "name": "Truck-New",
    "plate": "XYZ-9999",
    "status": "A",
    "createdAt": "2026-04-04T14:30:00"
  },
  "meta": {}
}

Error responses

When an error occurs, data is always null and the error object contains the details. See Error Handling for the full reference.

{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "\"limit\" must be a number between 1 and 100"
  }
}

---

Pagination

List endpoints support limit/offset pagination through query parameters:

Parameter	Type	Default	Max	Description
limit	integer	25	100	Number of records per page
offset	integer	0	—	Number of records to skip. On report endpoints it advances in whole pages — see below

Examples

First page (default):

GET /apidev/v1/fleet/devices?limit=25&offset=0
→ records 1–25

Second page:

GET /apidev/v1/fleet/devices?limit=25&offset=25
→ records 26–50

Third page:

GET /apidev/v1/fleet/devices?limit=25&offset=50
→ records 51–75

Report endpoints page in whole steps of limit

Reports (/reports/**) advance in complete pages, so offset is rounded down to the nearest multiple of limit. Asking for limit=25&offset=30 returns the same page as offset=25.

You always know what you got: meta.offset reports the offset actually applied, not the one you asked for. Keep offset a multiple of limit (0, 25, 50, …) and the behaviour is exactly what you expect.

Calculating total pages

const totalPages = Math.ceil(meta.total / meta.limit);
// total: 150, limit: 25 → 6 pages

Iterating through all pages

JavaScript

async function fetchAllPages(baseUrl, headers) {
  const limit = 100;
  let offset = 0;
  let allRecords = [];

  while (true) {
    const response = await fetch(
      `${baseUrl}?limit=${limit}&offset=${offset}`,
      { headers }
    );
    const json = await response.json();

    allRecords = allRecords.concat(json.data);

    if (offset + limit >= json.meta.total) break;
    offset += limit;
  }

  return allRecords;
}

// Usage
const devices = await fetchAllPages(
  `https://${TENANT}/apidev/v1/fleet/devices`,
  headers
);

Python

def fetch_all_pages(base_url, headers):
    limit = 100
    offset = 0
    all_records = []

    while True:
        response = requests.get(
            base_url,
            headers=headers,
            params={"limit": limit, "offset": offset},
        )
        json_data = response.json()

        all_records.extend(json_data["data"])

        if offset + limit >= json_data["meta"]["total"]:
            break
        offset += limit

    return all_records

# Usage
devices = fetch_all_pages(
    f"https://{TENANT}/apidev/v1/fleet/devices",
    headers
)

tip

Set limit=100 (the maximum) when iterating through all pages to minimize the number of API calls and stay within rate limits.

---

Filters and Pagination

Filters are applied before pagination. The meta.total value reflects the count of records that match your filters, not the total in the database.

GET /apidev/v1/fleet/devices?status=A&limit=25&offset=0

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "total": 42,
    "limit": 25,
    "offset": 0
  }
}

In this example, 42 devices have status=A — not 42 total devices in the system. Page calculations should use this filtered total.

---

Sort Order

List endpoints return results in a deterministic order, typically by primary key or creation date descending (newest first). Individual endpoint documentation specifies the default sort when it differs from this convention.

The API does not expose a generic sort query parameter — the sort order is fixed per endpoint to ensure consistent pagination across pages.

---

Empty Results

When a query matches no records, the response uses the standard envelope with an empty array:

{
  "success": true,
  "data": [],
  "meta": {
    "total": 0,
    "limit": 25,
    "offset": 0
  }
}

This is not an error — success is true. Your code should handle empty data arrays gracefully rather than treating them as failures.

warning

The maximum allowed value for limit is 100. Requesting a higher value returns a VALIDATION_ERROR.