Skip to content
Transdirect Developer Centre

v4 vs v5 — which should I use?

Transdirect runs two API generations side by side. Both are live, both are supported, and both talk to the same members, bookings, and couriers. This page is orientation, not a migration cookbook — it tells you which one to build against and why.

Short version: new integration → v5. Existing v4 integration → keep going, migrate whenever it suits you.

At a glance

Section titled “At a glance”
v5 (recommended)v4 (existing)
Base URLhttps://api.transdirect.com.auhttps://www.transdirect.com.au/api
Version in pathAlways — /api/v5/...Booking routes only — /api/bookings/v4/...; quotes, orders, locations and members are unversioned
Typed SDKYes — @transdirect/api-sdk on npmNo
OpenAPI spec + ExplorerYes — /openapi.json and the API ExplorerNo — the original docs lived on Apiary
AuthenticationApi-Key headerApi-Key header or HTTP Basic (email + password)
Recommended forNew integrations, TypeScript/JavaScript stacks, AI agentsExisting integrations, and anything already built on the v4 reference pages

Behaviour is shared where it matters: JSON everywhere, AUD, ISO 8601 dates, and the same demo mode (a flag on your normal key, not a separate sandbox key). Note that rate limits and 429 response shapes differ between the generations (v5 allows far more requests per minute) — see rate limits.

New integration → v5

Section titled “New integration → v5”

Start at https://api.transdirect.com.au with the typed SDK:

import { client, postApiV5Quotes } from '@transdirect/api-sdk';


client.setConfig({
  baseUrl: 'https://api.transdirect.com.au',
  headers: { 'Api-Key': process.env.TD_API_KEY! },
});


const { data, error } = await postApiV5Quotes({ body: { /* ... */ } });

What you get over v4:

  • Types that can’t drift. The SDK is generated from the API’s OpenAPI spec, so the shapes you code against are exactly what the API accepts and returns.
  • A machine-readable contract. The spec at /openapi.json powers the API Explorer, and any OpenAPI generator can produce a client in your language from it.
  • The full booking lifecycle, versioned. Quotes, pickup availability, booking create/confirm/get, items CRUD, labels (including A6) and manifests, tracking, locations, customs declarations, and API-key configuration are all exposed as typed SDK functions.
  • Predictable versioning. Semver keyed off the spec; the URL path only changes on a major.

Not on TypeScript? Use v5 anyway — it’s plain REST with an Api-Key header, and the spec gives you a generated client in most languages.

Existing v4 integration → stays supported

Section titled “Existing v4 integration → stays supported”

v4 is the existing API, and it is fully supported — nothing about your current integration needs to change. The reference pages on this site document v4 in full, curl samples included, starting with create a booking.

When you do want to move, the jump is smaller than it looks: the v5 booking routes are shaped /api/v5/bookings/v4/..., deliberately mirroring the v4 booking lifecycle. Your existing mental model — create with quotes, confirm, fetch labels, track — carries straight over; mostly you’re swapping the base URL and picking up the SDK’s types.

For AI agents / MCP

Section titled “For AI agents / MCP”

If you’re building an LLM-driven agent (or wiring Transdirect into an MCP server), consume the API through its machine-readable entry points rather than scraping these docs:

  • OpenAPI spec — https://api.transdirect.com.au/openapi.json. The complete v5 contract: every route, parameter, and response schema.
  • llms.txt — this site publishes an llms.txt index of its documentation, built for LLM consumption.
  • Typed SDK — @transdirect/api-sdk gives agents that generate or execute TypeScript a validated, typed surface instead of hand-rolled HTTP.

Demo mode is the safe default for agent experimentation: with the demo flag on your key, confirming with payment_method: "demo" produces a real end-to-end booking flow — DEMO-XXXXXXXX connote, watermarked test labels — with no charge and no carrier lodgement.

Next steps

Section titled “Next steps”