Core Concepts

Pagination

All list endpoints return paginated responses with a consistent envelope.

Response envelope

Every list endpoint wraps results in a standard paginated envelope:

{
  "data": [
    { "id": "load_550e8400-...", "load_number": "LD-001" },
    { "id": "load_662f9b11-...", "load_number": "LD-002" }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_count": 150,
    "total_pages": 8
  }
}

Query parameters

Control pagination with two query parameters:

ParameterTypeDefaultDescription
pageinteger1The page number to retrieve (1-indexed).
page_sizeinteger20Number of results per page. Maximum 100.

Example request

curl "https://tryenvoy.ai/api/v1/loads?page=2&page_size=50" \
  -H "X-API-Key: <your-api-key>"

Response:

{
  "data": [
    { "id": "load_a3c7e912-...", "load_number": "LD-051" },
    { "id": "load_b4d8f023-...", "load_number": "LD-052" }
  ],
  "pagination": {
    "page": 2,
    "page_size": 50,
    "total_count": 150,
    "total_pages": 3
  }
}

Pagination fields

FieldTypeDescription
pageintegerCurrent page number.
page_sizeintegerNumber of results returned per page.
total_countintegerTotal number of results across all pages.
total_pagesintegerTotal number of pages.

Iterating through pages

Use total_pages to determine when to stop:

import requests
url = "https://tryenvoy.ai/api/v1/loads"
headers = {"X-API-Key": "<your-api-key>"}
page = 1
while True:
    response = requests.get(url, headers=headers, params={"page": page, "page_size": 100})
    data = response.json()
    for load in data["data"]:
        process(load)
    if page >= data["pagination"]["total_pages"]:
        break
    page += 1
const headers = { "X-API-Key": "<your-api-key>" };
let page = 1;
while (true) {
  const res = await fetch(
    `https://tryenvoy.ai/api/v1/loads?page=${page}&page_size=100`,
    { headers }
  );
  const { data, pagination } = await res.json();
  for (const load of data) {
    process(load);
  }
  if (page >= pagination.total_pages) break;
  page++;
}

Sorting

Some list endpoints support sorting via order_by and order_desc parameters:

ParameterTypeDefaultDescription
order_bystringcreated_atField to sort by.
order_descbooleantrueSort in descending order.
curl "https://tryenvoy.ai/api/v1/loads?order_by=created_at&order_desc=false&page_size=50" \
  -H "X-API-Key: <your-api-key>"

List endpoints that support search accept a search query parameter for full-text filtering:

curl "https://tryenvoy.ai/api/v1/carriers?search=midwest&page_size=20" \
  -H "X-API-Key: <your-api-key>"

The search parameter filters across relevant fields for each resource (e.g., name, MC number, and DOT number for carriers).