Developer guide

Make a REST request

From your Pro workspace, create a scoped key. Set TRUCKERFETCH_ORIGIN to the HTTPS site origin and load your key into TRUCKERFETCH_API_KEY in your environment. Start with edition metadata.

curl --fail-with-body "$TRUCKERFETCH_ORIGIN/api/v1/editions/latest" \
  -H "Authorization: Bearer $TRUCKERFETCH_API_KEY"

Search the catalog

curl --fail-with-body "$TRUCKERFETCH_ORIGIN/api/v1/carriers/search" \
  -H "Authorization: Bearer $TRUCKERFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"filters":{"states":["TX"],"fleet":{"min":1,"max":10}},"limit":20}'

Follow the response’s opaque next cursor using the same filters. An empty publication is a valid result. The initial baseline may exist before the first daily edition. Add contact scope only when your integration needs reported contact fields.

Connect a remote MCP client

1. Use the hosted HTTPS endpoint at /api/mcp on your TruckerFetch origin.
2. Complete the client’s OAuth sign-in flow. Check the requesting client, proposed scopes and selected account before approving.
3. Try the read-only get_latest_edition tool, then search_carriers. Ask “Which edition was last published, and when was its source observed?”

In ChatGPT, choose a predefined OAuth client with ID truckerfetch-chatgpt. In Claude, choose “Use your own OAuth client” with ID truckerfetch-claude. Both use a public client, so leave the secret empty.

In Cursor, add this entry to the mcpServers object in mcp.json.

{
  "truckerfetch": {
    "url": "https://truckerfetch.com/api/mcp",
    "auth": {
      "CLIENT_ID": "truckerfetch-cursor",
      "scopes": [
        "data:read"
      ]
    }
  }
}

REST keys never belong in a chat prompt. Review or revoke connected apps under Connected apps.

Verify a signed webhook

Register an HTTPS destination, store its one-time signing secret and send a test event. Read the raw request bytes before parsing JSON. Verify timestamp and signature, then claim the event ID in durable storage before processing or acknowledging it.

import {createHmac, timingSafeEqual} from "node:crypto"

function verify(headers, rawBody, secret) {
  const id = headers.get("TruckerFetch-Event-Id")
  const ts = headers.get("TruckerFetch-Timestamp")
  const sig = headers.get("TruckerFetch-Signature") || ""
  if (!id || !/^\d+$/.test(ts || "") || !/^v1=[a-f0-9]{64}$/.test(sig)) return false
  if (Math.abs(Date.now()/1000 - Number(ts)) > 300) return false
  const expected = createHmac("sha256", Buffer.from(secret, "base64url"))
    .update(id + "." + ts + ".").update(rawBody).digest()
  return timingSafeEqual(expected, Buffer.from(sig.slice(3), "hex"))
}

Attempts can arrive more than once or out of order. Use the authenticated API to retrieve authorized data and the webhook dashboard to review delivery attempts.