Truckers Hub
Sign in

Guides

API guide

Read what is public about VTCs and drivers, and with a key do a little more. JSON in, JSON out.

The basics

  • Base address: https://truckers-hub.com/api/v1. The machine readable description is at /api/v1/openapi.json.
  • Public data needs no key, at 60 requests a minute per address. With a key it is 600 a minute per key.
  • VTC staff make keys under Manage, API and webhooks. Send one as Authorization: Bearer thv_.... A key belongs to one VTC and only opens private data for that VTC.
  • Answers look like { "data": ... }. Lists that continue add next: pass it back as before. Errors look like { "error": { "code", "message" } }.
  • Anyone may call it from a web page: cross origin requests are allowed.
curl https://truckers-hub.com/api/v1/vtcs/your-vtc/leaderboard?limit=5

Endpoints

GET /vtcs

List the VTCs in the directory, featured ones first.

q Search by name or address
game ets2 or ats
recruiting 1 for only those recruiting
page Page number
limit Up to 50
GET /vtcs/{slug}

One VTC.

GET /vtcs/{slug}/members

Members with their points and roles, in the order they joined.

q Search by name
page Page number
limit Up to 100
GET /vtcs/{slug}/leaderboard

The ranking by points.

period all or month
limit Up to 100
GET /vtcs/{slug}/jobs

Jobs, newest first. Pass the next value back as before to get the following page.

limit Up to 100
before The next value from the last page
status delivered or cancelled
driver A driver id
GET /vtcs/{slug}/ranks

The ranks and the points each starts at.

GET /vtcs/{slug}/challenges

Challenges that are running or have ended, with the top five of each running one.

GET /vtcs/{slug}/divisions

Divisions with their size and deliveries.

GET /vtcs/{slug}/fleet

The trucks and garages the VTC owns. Prices and upkeep are not included.

GET /vtcs/{slug}/announcements

Public announcements, pinned first.

limit Up to 50
GET /drivers/{id}

A public driver profile with career totals. Private profiles return 404.

GET /vtcs/{slug}/walletkey: wallet

The company wallet: balance, share of each delivery and the last hundred entries.

POST /vtcs/{slug}/announcementskey: announce

Post an announcement as the person who made the key.

Body: { "title": "string", "body": "string", "pinned": false, "public": true }

GET /map/{game}

The community map for ets2 or ats: squares of road drivers have used, as [cx, cz, hits], and the cities seen, in game metres. One square is cell metres wide.

GET /me

Which VTC and scopes the key in use belongs to.

Webhooks

Staff add an https address and pick the events. Each delivery is a POST with this body and headers:

{ "id": "uuid", "type": "job.delivered", "createdAt": "2026-10-21T10:02:02Z", "data": { ... } }

x-truckers-event: job.delivered
x-truckers-signature: sha256=<hex hmac of the raw body made with your secret>

Answer with any 2xx status. A delivery is tried once, and a webhook that fails twenty times in a row turns itself off until staff turn it back on. Events:

  • job.delivered A driver delivered a job.
  • job.cancelled A driver cancelled a job.
  • job.removed Staff removed a job.
  • member.joined Someone joined the VTC.
  • member.left Someone left or was removed.
  • rank.up A driver reached a new rank.
  • challenge.completed A driver finished a challenge.