Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tread.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Horizon API is a REST API that returns JSON. It conforms to OpenAPI 3.0.3 and covers the same data your team manages in the Tread Horizon app — projects, orders, dispatch, tickets, settlements, and more. Every endpoint listed in this reference is auto-generated from the live spec.

​
Base URL

All requests go to a single host. There is one production server today. 
https://api.tread-horizon.com
Sandbox access is provisioned per customer. Contact developers@tread.io to request a sandbox tenant.

​
Authentication

The API uses bearer tokens. Two flows exist depending on who is calling.
  • User session tokens — for human users. Stytch issues a short-lived JWT after a user logs in (email + password, magic link, or SSO). Use this when building tools that act on behalf of a signed-in user.
  • Machine-to-machine (M2M) tokens — for server-to-server integrations. Tread issues a Client ID and Client Secret. Exchange them at the auth endpoint for an access token using the OAuth 2.0 client credentials grant.
Send the token on every request as a Bearer header. 
Authorization: Bearer <access_token>
Tokens expire. When you get a 401 unauthorized, fetch a new one. See Generate an auth token for the exact request shape, plus the rest of the Authentication group in the sidebar. To get M2M credentials, email developers@tread.io.

​
Required headers

HeaderRequiredValue
AuthorizationYesBearer <token>
Content-TypeOn POST, PUT, PATCHapplication/json
AcceptNoapplication/json (default)
Accept-LanguageNoen-ca, es-us, or fr-ca. Translates error messages.
An invalid Content-Type returns 415 unsupported_media_type. An invalid Accept returns 406 not_acceptable.

​
Pagination

List endpoints use cursor-based pagination. Pass page[limit] to set page size. The default is 25 and the maximum is 100. 
GET /v1/companies/{company-id}/projects?page[limit]=25
The response includes a Link header with next and prev URLs when more results exist. 
Link: <https://api.tread-horizon.com/v1/companies/abc/projects?page[limit]=25&page[after]=Ij...>; rel="next"
Follow the next link until the header no longer includes one. The page[after] cursor is opaque — do not parse it.

​
Errors

Every error response uses the same envelope. The code mirrors the HTTP status. 
{
  "error": {
    "code": "unprocessable_content",
    "errors": [
      { "model": "User", "field": "email", "message": "email is required" }
    ]
  }
}
HTTPcodeWhen you’ll see it
400bad_requestMalformed request.
401unauthorizedMissing or expired token.
403forbiddenThe user lacks permission for this action.
404object_not_foundThe resource does not exist or is not visible.
409conflictThe action violates a state machine rule.
415unsupported_media_typeContent-Type is wrong.
422unprocessable_contentValidation failed. The errors array names the field.
500internal_server_errorReach out to support.
503service_unavailableRetry after a short backoff. Requests time out at 60 seconds.
409 and 422 responses include an errors array with model, field, and message fields you can surface to end users.

​
Resources

The API exposes most of what Horizon manages. Major resource families:
FamilyNotes
Projects, Orders, Jobs, LoadsThe dispatch hierarchy. A project holds orders. An order holds jobs. A job is one driver’s work. A load is one cycle.
Tickets, Timesheets, DriverDaysProof of work. Tickets capture material. DriverDays capture hours.
Users, Drivers, ForemenPeople with access — defined by Roles and Permissions.
SitesPickup and delivery locations with geofences.
Companies, CompanySharesThe company you operate as, plus parent/child relationships.
Equipment, EquipmentTypesTrucks and the type they belong to. Capacity lives on the Type.
Materials, MaterialRatesWhat you haul and how it is priced.
Rates, AddOns, FuelSurchargesThe pricing model — base rates, fees, fuel adjustments.
Settlements, InvoicesDriver/vendor pay and customer billing.
Integrations, Telematics, AgaveConnections to QuickBooks, Sage, Samsara, Geotab, paver telemetry, and HCSS.
Each family has its own group in the left-hand sidebar. Click in to see the endpoints, request shape, and a try-it-out console.

​
Webhooks

Tread can push events to your endpoint when records change — orders accepted, loads approved, tickets created, and more. Webhooks are configured per company. See the Webhooks integration page for setup, retry behavior, and the event catalog.

​
Child companies and multi-entity

A company can have a parent. A user in the parent has the same role and permission level in every child. Most endpoints scope to a company via the URL — for example, GET /v1/companies/{company-id}/projects lists projects for one specific company. Use the company-scoped variant when you need to read or write data inside a child. parent_company_id is set at creation and cannot be changed. Circular references are rejected. List child companies with GET /v1/companies/{company-id}/children.

​
Quick example

Fetch the first page of projects for a company. 
curl https://api.tread-horizon.com/v1/companies/{company-id}/projects \
  -H "Authorization: Bearer $TREAD_TOKEN" \
  -H "Accept: application/json"
Sample response: 
{
  "data": [
    {
      "id": "f0a1...",
      "name": "Highway 401 Resurfacing",
      "external_id": "PRJ-2025-014",
      "starts_on": "2025-05-01",
      "ends_on": "2025-09-30",
      "company_id": "abc...",
      "customer_id": "cust...",
      "created_at": "2025-04-12T14:22:10Z"
    }
  ]
}

​
Going further

Generate an auth token

Log in and exchange credentials for a bearer token.

Webhooks

Subscribe to events and receive them in real time.

Tread Horizon app

Sign in to the platform that backs this API.

Status

Live uptime and incident history.