> ## 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.
# Introduction
> Build on top of Tread Horizon — the operating system for bulk materials hauling.
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](mailto: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.
```bash theme={null}
Authorization: Bearer
```
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](mailto:developers@tread.io).
## Required headers
| Header | Required | Value |
| ----------------- | ------------------------- | -------------------------------------------------------- |
| `Authorization` | Yes | `Bearer ` |
| `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`.
```bash theme={null}
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: ; 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.
```json theme={null}
{
"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](mailto:support@tread.io). |
| 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](/concepts/orders-projects), Jobs, Loads | The dispatch hierarchy. A Project holds Orders. An Order holds Jobs. A Job is one [Driver's](/concepts/driver-lifecycle) work. A Load is one cycle. |
| [Tickets](/concepts/tickets-timesheets), 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](/concepts/roles-permissions). |
| [Sites](/concepts/sites-geofences) | Pickup and delivery locations with geofences. |
| [Companies](/concepts/companies-hierarchy), 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](/concepts/equipment) | Individual truck or trailer records. Capacity and unit of measure live on the Equipment Type. |
| [Materials, MaterialRates](/concepts/materials) | The Material record for what an Order moves. A MaterialRate prices a Material. |
| [Rates, AddOns, FuelSurcharges](/concepts/rates-add-ons) | The pricing model — base Rates, Add-Ons, and fuel surcharges. |
| [Settlements](/concepts/settlements-driver-pay), Invoices | A Settlement is a batch of approved work, ready to bill or pay. Invoices bill Customers. |
| Integrations, Telematics, Agave | Connections to accounting ([QuickBooks](/integrations/quickbooks), [Sage](/integrations/sage), Vista, Foundation, Spectrum), [telematics](/integrations/telematics) (Samsara, Geotab), [Paver Tracker](/integrations/paver-tracker), and [HCSS](/integrations/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](/integrations/webhooks) for setup, retry behavior, and the event catalog.
## Parent and child companies
A [company can have a parent](/concepts/companies-hierarchy). 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.
```bash theme={null}
curl https://api.tread-horizon.com/v1/companies/{company-id}/projects \
-H "Authorization: Bearer $TREAD_TOKEN" \
-H "Accept: application/json"
```
Sample response:
```json theme={null}
{
"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
Log in and exchange credentials for a bearer token.
Subscribe to events and receive them in real time.
Sign in to the platform that backs this API.
Bulk-load Orders, Projects, Tickets, and Files with async ingest endpoints.
Live uptime and incident history.