DEVELOPER PLATFORM

Build on Canada's
mobility infrastructure

REST APIs for carrier integration, parcel tracking and live GPS telemetry — with sovereign, in-region data handling.

API reference OpenAPI 3.0 spec Postman collection

Quick start

A carrier admin issues you a key from Manage → API Keys. Verify it first — /api/v1/ping tells you the key works and which carrier it is scoped to.

curl https://transia1.com/api/v1/ping \
  -H "Authorization: Bearer $TRANSIA_KEY"

const res = await fetch("https://transia1.com/api/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.TRANSIA_KEY}` },
});
console.log(await res.json());

$res = Http::withToken(env('TRANSIA_KEY'))
    ->get('https://transia1.com/api/v1/ping');

$res->json();

import os, requests

r = requests.get("https://transia1.com/api/v1/ping",
                 headers={"Authorization": f"Bearer {os.environ['TRANSIA_KEY']}"})
print(r.json())

{
  "ok": true,
  "operator": { "id": 3, "name": "Maple Transit" },
  "time": "2026-09-04T23:15:08-04:00"
}

Authentication

Two schemes, for two different callers.

Vendor API key Server to server, for a carrier's own systems. Send it as Authorization: Bearer or X-API-Key. Every request is scoped to the carrier that owns the key.

Device-bound JWT For mobile apps and SPAs. Exchange credentials at /api/auth/token, then send the access token with X-Device-Id. Tokens are pinned to the device that requested them.

Keys are stored only as a SHA-256 hash — the secret is shown once, at issue or rotation, and cannot be recovered afterwards. Lost one? Rotate it. A key also stops working the moment its carrier stops being active, so suspending a carrier closes every integration it holds without anyone hunting through this list.

API reference

11 endpoints, read from this deployment's own route table — so this list is what is actually running, not what someone remembered to write down.

Vendor API key

Server to server. One key belongs to one carrier and can never read another carrier's data.

GET /api/v1/ping Confirm a key works and see which carrier it is scoped to.

The cheapest way to verify a newly issued or rotated key before you deploy it.

Vendor API key Try it below

curl https://transia1.com/api/v1/ping \
  -H "Authorization: Bearer $TRANSIA_KEY"

const res = await fetch("https://transia1.com/api/v1/ping", {
  headers: { "Authorization": `Bearer ${process.env.TRANSIA_KEY}` },
});

console.log(res.status, await res.json());

$res = Http::withToken(env('TRANSIA_KEY'))
    ->get('https://transia1.com/api/v1/ping');

$res->json();

import os, requests

r = requests.get("https://transia1.com/api/v1/ping", headers={"Authorization": f"Bearer {os.environ["TRANSIA_KEY"]}"})
print(r.status_code, r.json())

{
  "ok": true,
  "operator": { "id": 3, "name": "Maple Transit" },
  "time": "2026-01-01T09:00:00+00:00"
}

GET /api/v1/routes Every route this carrier operates.

Vendor API key Try it below

curl https://transia1.com/api/v1/routes \
  -H "Authorization: Bearer $TRANSIA_KEY"

const res = await fetch("https://transia1.com/api/v1/routes", {
  headers: { "Authorization": `Bearer ${process.env.TRANSIA_KEY}` },
});

console.log(res.status, await res.json());

$res = Http::withToken(env('TRANSIA_KEY'))
    ->get('https://transia1.com/api/v1/routes');

$res->json();

import os, requests

r = requests.get("https://transia1.com/api/v1/routes", headers={"Authorization": f"Bearer {os.environ["TRANSIA_KEY"]}"})
print(r.status_code, r.json())

{
  "data": [
    {
      "id": 17, "code": "B502", "origin": "Toronto Union",
      "destination": "Ottawa Station", "mode": "bus",
      "base_fare": "64.00", "distance_km": "450.00", "status": "active"
    }
  ]
}

GET /api/v1/schedules Upcoming departures, soonest first. Paginated, 50 per page.

Only departures still in the future come back, so polling this endpoint never walks backwards through history.

Vendor API key Paginated · 50 / page Try it below

Query

page	optional · 1-based page number, 50 rows per page

curl https://transia1.com/api/v1/schedules \
  -H "Authorization: Bearer $TRANSIA_KEY"

const res = await fetch("https://transia1.com/api/v1/schedules", {
  headers: { "Authorization": `Bearer ${process.env.TRANSIA_KEY}` },
});

console.log(res.status, await res.json());

$res = Http::withToken(env('TRANSIA_KEY'))
    ->get('https://transia1.com/api/v1/schedules');

$res->json();

import os, requests

r = requests.get("https://transia1.com/api/v1/schedules", headers={"Authorization": f"Bearer {os.environ["TRANSIA_KEY"]}"})
print(r.status_code, r.json())

{
  "data": [
    {
      "id": 8821, "route": "B502",
      "origin": "Toronto Union", "destination": "Ottawa Station",
      "departs_at": "2026-01-01T14:30:00+00:00",
      "available_seats": 18, "price": 64.0,
      "status": "scheduled", "delay_minutes": 0
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 214, "last_page": 5 }
}

GET /api/v1/bookings Bookings sold against this carrier.

Newest first. Only bookings on your own routes are visible — the scope comes from the key, not from a filter you pass.

Vendor API key Paginated · 50 / page Try it below

Query

page	optional · 1-based page number, 50 rows per page

curl https://transia1.com/api/v1/bookings \
  -H "Authorization: Bearer $TRANSIA_KEY"

const res = await fetch("https://transia1.com/api/v1/bookings", {
  headers: { "Authorization": `Bearer ${process.env.TRANSIA_KEY}` },
});

console.log(res.status, await res.json());

$res = Http::withToken(env('TRANSIA_KEY'))
    ->get('https://transia1.com/api/v1/bookings');

$res->json();

import os, requests

r = requests.get("https://transia1.com/api/v1/bookings", headers={"Authorization": f"Bearer {os.environ["TRANSIA_KEY"]}"})
print(r.status_code, r.json())

{
  "data": [
    {
      "reference": "TRX-58001", "status": "confirmed", "passengers": 2,
      "total": 128.0, "currency": "CAD",
      "created_at": "2026-01-01T09:14:02+00:00"
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 63, "last_page": 2 }
}

GET /api/v1/parcels Parcels this carrier is carrying.

Vendor API key Paginated · 50 / page Try it below

Query

page	optional · 1-based page number, 50 rows per page

curl https://transia1.com/api/v1/parcels \
  -H "Authorization: Bearer $TRANSIA_KEY"

const res = await fetch("https://transia1.com/api/v1/parcels", {
  headers: { "Authorization": `Bearer ${process.env.TRANSIA_KEY}` },
});

console.log(res.status, await res.json());

$res = Http::withToken(env('TRANSIA_KEY'))
    ->get('https://transia1.com/api/v1/parcels');

$res->json();

import os, requests

r = requests.get("https://transia1.com/api/v1/parcels", headers={"Authorization": f"Bearer {os.environ["TRANSIA_KEY"]}"})
print(r.status_code, r.json())

{
  "data": [
    {
      "tracking_number": "TRP-4471903", "status": "in_transit",
      "recipient": "A. Tremblay",
      "origin": "Toronto Hub", "destination": "Ottawa Hub",
      "price": 24.6, "eta": "2026-01-02T17:00:00+00:00"
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 12, "last_page": 1 }
}

PATCH /api/v1/parcels/{parcel}/status Move a parcel to its next state.

Runs the parcel state machine, so an illegal transition is refused with 422 rather than silently written. The legal moves are the ones drawn in the lifecycle below.

Vendor API key

Body

status	required · one of the parcel statuses
location	optional · free text, max 160 chars
note	optional · free text, max 240 chars

curl -X PATCH https://transia1.com/api/v1/parcels/{parcel}/status \
  -H "Authorization: Bearer $TRANSIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "out_for_delivery",
    "location": "Ottawa Hub",
    "note": "On van 12"
}'

const payload = {
    "status": "out_for_delivery",
    "location": "Ottawa Hub",
    "note": "On van 12"
};

const res = await fetch("https://transia1.com/api/v1/parcels/{parcel}/status", {
  method: "PATCH",
  headers: { "Authorization": `Bearer ${process.env.TRANSIA_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

console.log(res.status, await res.json());

$payload = [
    'status' => 'out_for_delivery',
    'location' => 'Ottawa Hub',
    'note' => 'On van 12',
];

$res = Http::withToken(env('TRANSIA_KEY'))
    ->patch('https://transia1.com/api/v1/parcels/{parcel}/status', $payload);

$res->json();

import os, requests

payload = {
    "status": "out_for_delivery",
    "location": "Ottawa Hub",
    "note": "On van 12"
}

r = requests.patch("https://transia1.com/api/v1/parcels/{parcel}/status", headers={"Authorization": f"Bearer {os.environ["TRANSIA_KEY"]}"}, json=payload)
print(r.status_code, r.json())

{
  "data": {
    "tracking_number": "TRP-4471903", "status": "out_for_delivery",
    "recipient": "A. Tremblay",
    "origin": "Toronto Hub", "destination": "Ottawa Hub",
    "price": 24.6, "eta": "2026-01-02T17:00:00+00:00"
  }
}

GET /api/v1/freight-orders Freight orders assigned to this carrier.

Vendor API key Paginated · 50 / page Try it below

Query

page	optional · 1-based page number, 50 rows per page

curl https://transia1.com/api/v1/freight-orders \
  -H "Authorization: Bearer $TRANSIA_KEY"

const res = await fetch("https://transia1.com/api/v1/freight-orders", {
  headers: { "Authorization": `Bearer ${process.env.TRANSIA_KEY}` },
});

console.log(res.status, await res.json());

$res = Http::withToken(env('TRANSIA_KEY'))
    ->get('https://transia1.com/api/v1/freight-orders');

$res->json();

import os, requests

r = requests.get("https://transia1.com/api/v1/freight-orders", headers={"Authorization": f"Bearer {os.environ["TRANSIA_KEY"]}"})
print(r.status_code, r.json())

{
  "data": [
    {
      "tracking_number": "TRF-90210", "origin": "Halifax Port",
      "destination": "Montreal Yard", "plan": "Rail 1 leg · 1,247 km",
      "status": "in_transit", "total_cost": 4820.0,
      "eta": "2026-01-04T06:00:00+00:00"
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 4, "last_page": 1 }
}

POST /api/v1/telemetry/positions Push real GPS/AVL positions. Batched, up to 1000 per call.

Rows are validated individually: a bad row comes back reported by index and the rest of the batch still lands, so one malformed vehicle never costs you the whole push.

Vendor API key 600 / minute

Body

positions[].vehicle_ref	required · your own vehicle id, max 64 chars
positions[].lat	required · -90 to 90
positions[].lng	required · -180 to 180
positions[].reported_at	required · ISO 8601 timestamp
positions[].route_code	optional · a route code you operate
positions[].heading	optional · 0-359
positions[].speed_kmh	optional · 0-600
positions[].occupancy_pct	optional · 0-100
positions[].status	optional · in_transit_to \| stopped_at \| incoming_at
positions[].stop_ref	optional · max 64 chars

curl -X POST https://transia1.com/api/v1/telemetry/positions \
  -H "Authorization: Bearer $TRANSIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positions": [
        {
            "vehicle_ref": "BUS-114",
            "route_code": "B502",
            "lat": 43.6452,
            "lng": -79.3806,
            "heading": 84,
            "speed_kmh": 47,
            "occupancy_pct": 62,
            "status": "in_transit_to",
            "reported_at": "2026-01-01T09:00:00Z"
        }
    ]
}'

const payload = {
    "positions": [
        {
            "vehicle_ref": "BUS-114",
            "route_code": "B502",
            "lat": 43.6452,
            "lng": -79.3806,
            "heading": 84,
            "speed_kmh": 47,
            "occupancy_pct": 62,
            "status": "in_transit_to",
            "reported_at": "2026-01-01T09:00:00Z"
        }
    ]
};

const res = await fetch("https://transia1.com/api/v1/telemetry/positions", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.TRANSIA_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

console.log(res.status, await res.json());

$payload = [
    'positions' => [
        [
            'vehicle_ref' => 'BUS-114',
            'route_code' => 'B502',
            'lat' => 43.6452,
            'lng' => -79.3806,
            'heading' => 84,
            'speed_kmh' => 47,
            'occupancy_pct' => 62,
            'status' => 'in_transit_to',
            'reported_at' => '2026-01-01T09:00:00Z',
        ],
    ],
];

$res = Http::withToken(env('TRANSIA_KEY'))
    ->post('https://transia1.com/api/v1/telemetry/positions', $payload);

$res->json();

import os, requests

payload = {
    "positions": [
        {
            "vehicle_ref": "BUS-114",
            "route_code": "B502",
            "lat": 43.6452,
            "lng": -79.3806,
            "heading": 84,
            "speed_kmh": 47,
            "occupancy_pct": 62,
            "status": "in_transit_to",
            "reported_at": "2026-01-01T09:00:00Z"
        }
    ]
}

r = requests.post("https://transia1.com/api/v1/telemetry/positions", headers={"Authorization": f"Bearer {os.environ["TRANSIA_KEY"]}"}, json=payload)
print(r.status_code, r.json())

{
  "accepted": 998,
  "rejected": 2,
  "errors": [
    { "index": 41, "errors": ["reported_at is in the future — check the sender clock."] },
    { "index": 77, "errors": ["The lat field must be between -90 and 90."] }
  ]
}

Device-bound JWT

For mobile apps and SPAs. Access tokens are pinned to the device that asked for them.

GET /api/auth/me The account behind the current access token.

Device-bound JWT

curl https://transia1.com/api/auth/me \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Device-Id: $DEVICE_ID"

const res = await fetch("https://transia1.com/api/auth/me", {
  headers: { "Authorization": `Bearer ${process.env.ACCESS_TOKEN}`, "X-Device-Id": `${process.env.DEVICE_ID}` },
});

console.log(res.status, await res.json());

$res = Http::withToken($accessToken)
    ->withHeaders(['X-Device-Id' => $deviceId])
    ->get('https://transia1.com/api/auth/me');

$res->json();

import os, requests

r = requests.get("https://transia1.com/api/auth/me", headers={"Authorization": f"Bearer {os.environ["ACCESS_TOKEN"]}", "X-Device-Id": f"{os.environ["DEVICE_ID"]}"})
print(r.status_code, r.json())

{
  "user": {
    "id": 42, "name": "Jose Ramirez", "email": "jose@example.ca",
    "role": "citizen", "region": "ON", "kyc_level": 2
  },
  "token": { "jti": "b1f0...", "expires_at": 1767225600, "device_bound": true }
}

No authentication

Callable without credentials.

POST /api/auth/token Exchange credentials for a device-bound access + refresh token.

The device id is bound into the token, so presenting it from another device is rejected. Send otp as well when the account has two-factor enabled.

No authentication 10 / minute

Body

email	required · account email
password	required
device_id	required · stable id for this install, max 128 chars
otp	optional · needed when the account has 2FA on

curl -X POST https://transia1.com/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ops@carrier.ca",
    "password": "your-password",
    "device_id": "ios-9f3c1b7e"
}'

const payload = {
    "email": "ops@carrier.ca",
    "password": "your-password",
    "device_id": "ios-9f3c1b7e"
};

const res = await fetch("https://transia1.com/api/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

console.log(res.status, await res.json());

$payload = [
    'email' => 'ops@carrier.ca',
    'password' => 'your-password',
    'device_id' => 'ios-9f3c1b7e',
];

$res = Http::post('https://transia1.com/api/auth/token', $payload);

$res->json();

import requests

payload = {
    "email": "ops@carrier.ca",
    "password": "your-password",
    "device_id": "ios-9f3c1b7e"
}

r = requests.post("https://transia1.com/api/auth/token", json=payload)
print(r.status_code, r.json())

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 900,
  "device_id": "ios-9f3c1b7e"
}

POST /api/auth/token/refresh Trade a refresh token for a fresh access token.

Refresh tokens are bound to the same device as the token they replace.

No authentication 20 / minute

Body

refresh_token	required · the refresh token from /api/auth/token
device_id	required · must match the device the pair was issued to, max 128 chars

curl -X POST https://transia1.com/api/auth/token/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "device_id": "ios-9f3c1b7e"
}'

const payload = {
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "device_id": "ios-9f3c1b7e"
};

const res = await fetch("https://transia1.com/api/auth/token/refresh", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

console.log(res.status, await res.json());

$payload = [
    'refresh_token' => 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
    'device_id' => 'ios-9f3c1b7e',
];

$res = Http::post('https://transia1.com/api/auth/token/refresh', $payload);

$res->json();

import requests

payload = {
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "device_id": "ios-9f3c1b7e"
}

r = requests.post("https://transia1.com/api/auth/token/refresh", json=payload)
print(r.status_code, r.json())

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 900,
  "device_id": "ios-9f3c1b7e"
}

Try it live

Call this deployment with your own key and see the real response. Read-only endpoints only.

Your API key

Endpoint

Query string

The request goes straight from your browser to this deployment's API. Your key is never sent anywhere else, is not stored, and is cleared when you leave the page — but it is still a live credential, so use a staging key if you would rather not type a production one into a browser. Press Ctrl + Enter to send.

Errors & rate limits

Failures come back as JSON with the reason in error or message.

401	Missing API key, or the key is invalid, revoked, expired — or its carrier is no longer active.
403	The key is valid but not for this carrier's data.
404	The record does not exist, or belongs to another carrier. Deliberately indistinguishable, so the API cannot be used to probe for other carriers' ids.
422	Validation failed, or a state machine refused the transition. The body names the offending fields.
429	Rate limit exceeded. Limits are per key, so one carrier can never starve another.

Rate limits are shown on each endpoint above where one applies. Telemetry is deliberately generous — 600 / minute — because a whole fleet reports together.

Webhooks

parcel.status_changedParcel status changed

parcel.deliveredParcel delivered

booking.createdBooking created

disruption.reportedService disruption reported

pingTest ping

Delivery & retries

Attempts	5, then the delivery is parked for inspection.
Backoff	10 s, 1 min, 5 min, 15 min between attempts.
Timeout	5 seconds per attempt.
Success	Any 2xx. Anything else — including a timeout — counts as a failure and is retried.
X-Transia-Event	The event name, so you can route before you parse.
X-Transia-Signature	`sha256=<hmac_sha256(raw_body, endpoint_secret)>`

Retries mean the same event can arrive twice — a receiver that hangs up after processing will still be retried. Treat id as an idempotency key and ignore one you have already seen.

Payload

{
    "id": "evt_xxxxxxxxxxxxxxxxxxxx",
    "event": "parcel.status_changed",
    "created": "2026-01-01T09:00:00+00:00",
    "data": {
        "tracking_number": "TRP-4471903",
        "from": "in_transit",
        "to": "out_for_delivery",
        "location": "Ottawa Hub"
    }
}

Verifying the signature

HMAC the raw request body — not a re-encoded copy of the parsed JSON, whose key order and spacing will not match — with your endpoint secret, and compare in constant time.

$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $endpointSecret);

if (! hash_equals($expected, $_SERVER['HTTP_X_TRANSIA_SIGNATURE'] ?? '')) {
    http_response_code(403);
    exit;
}

$event = json_decode($raw, true);

import crypto from "node:crypto";

// express.raw({ type: "application/json" }) — keep the bytes, not a parsed body.
const expected = "sha256=" + crypto.createHmac("sha256", endpointSecret)
  .update(req.body).digest("hex");

const given = req.get("X-Transia-Signature") ?? "";
const ok = expected.length === given.length &&
  crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given));

if (!ok) return res.sendStatus(403);
const event = JSON.parse(req.body.toString());

import hmac, hashlib, json

raw = request.get_data()                      # bytes, before any parsing
expected = "sha256=" + hmac.new(
    endpoint_secret.encode(), raw, hashlib.sha256
).hexdigest()

if not hmac.compare_digest(expected, request.headers.get("X-Transia-Signature", "")):
    abort(403)

event = json.loads(raw)

Parcel lifecycle

The states PATCH /api/v1/parcels/{parcel}/status enforces, and the moves each one allows. Anything not drawn here is refused with 422 — so this is the graph to code against, rather than discovering it one rejected transition at a time in production.

Created
created

may move to picked_up cancelled

Picked Up
picked_up

may move to in_transit exception cancelled

In Transit
in_transit

may move to out_for_delivery exception

Out for Delivery
out_for_delivery

may move to delivered exception

Delivered
delivered

Terminal — nothing follows it.

Exception
exception

may move to in_transit out_for_delivery returned

Returned
returned

Terminal — nothing follows it.

Cancelled
cancelled

Terminal — nothing follows it.

GPS telemetry

Push real vehicle positions and the live map stops being a simulation. Batch up to 1000 rows a call; each row is validated on its own, so one bad vehicle never costs you the batch.

curl -X POST https://transia1.com/api/v1/telemetry/positions \
  -H "Authorization: Bearer $TRANSIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positions": [
      {
        "vehicle_ref": "BUS-114",
        "route_code": "B502",
        "lat": 43.6452, "lng": -79.3806,
        "heading": 84, "speed_kmh": 47,
        "occupancy_pct": 62,
        "status": "in_transit_to",
        "reported_at": "2026-09-04T23:15:08-04:00"
      }
    ]
  }'

{
  "accepted": 1,
  "rejected": 0,
  "errors": []
}

Parcel status pushes accept 8 states — the lifecycle above shows which of them each state may move to. Illegal transitions are refused with 422 rather than written.

Request API access API status