Introduction - Tread Docs

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 account.

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 in the Authentication group in the sidebar for the exact request shape. To get M2M credentials, email developers@tread.io.

Required headers

Header	Required	Value
`Authorization`	Yes	`Bearer <token>`
`Content-Type`	On `POST`, `PUT`, `PATCH`	`application/json`
`Accept`	No	`application/json` (default)
`Accept-Language`	No	`en-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" }
    ]
  }
}

HTTP	`code`	When you’ll see it
400	`bad_request`	Malformed request.
401	`unauthorized`	Missing or expired token.
403	`forbidden`	The user lacks permission for this action.
404	`object_not_found`	The resource does not exist or is not visible.
409	`conflict`	The action violates a state machine rule.
415	`unsupported_media_type`	`Content-Type` is wrong.
422	`unprocessable_content`	Validation failed. The `errors` array names the field.
500	`internal_server_error`	Reach out to support.
503	`service_unavailable`	Retry 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:

Family	Notes
Projects, Orders, Jobs, Loads	The dispatch hierarchy. A Project holds Orders. An Order holds Jobs. A Job is one Driver’s work. A Load is one cycle.
Tickets, DriverDays	Proof-of-work records. A Ticket records one Load. A DriverDay records a Driver’s hours for a shift — a Timesheet in the app.
Users, Drivers, Foremen	Users with access, scoped by Roles and Permissions.
Sites	Pickup and delivery locations with geofences.
Companies, CompanyShares	The account you operate as, and its parent/child structure. A CompanyShare is a one-way connection that shares records between accounts.
Equipment, EquipmentTypes	Individual truck or trailer records. Capacity and unit of measure live on the Equipment Type.
Materials, MaterialRates	The Material record for what an Order moves. A MaterialRate prices a Material.
Rates, AddOns, FuelSurcharges	The pricing model — base Rates, Add-Ons, and fuel surcharges.
Settlements, Invoices	A Settlement is a batch of approved work, ready to bill or pay. Invoices bill Customers.
Integrations, Telematics, Agave	Connections to accounting (QuickBooks, Sage, Vista, Foundation, Spectrum), telematics (Samsara, Geotab), Paver Tracker, 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.

Parent and child companies

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 read-only in the API. 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"
    }
  ]
}

​Base URL

​Authentication

​Required headers

​Pagination

​Errors

​Resources

​Webhooks

​Parent and child companies

​Quick example

​Going further

Generate an auth token

Webhooks

Tread Horizon app

Importer APIs (Beta)

Status

Base URL

Authentication

Required headers

Pagination

Errors

Resources

Webhooks

Parent and child companies

Quick example

Going further