Getting Started

Overview

The FreightCake API lets you programmatically quote, book, track, and manage LTL freight shipments. It follows REST conventions with JSON request/response bodies, Stripe-style resource envelopes, and cursor-based pagination.

Base URL:

https://api.freightcake.com/api/v1

Quick Start

1. Get your API key

Create an API key from the FreightCake dashboard under Settings → API Keys. You'll receive two keys:

Test key (fk_test_...) — for sandbox development with mock carriers
Live key (fk_live_...) — for production with real carrier rates

2. Get a freight quote

curl -X POST https://api.freightcake.com/api/v1/quotes \
  -H "Authorization: Bearer fk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "city": "Chicago", "state": "IL", "zip": "60601" },
    "destination": { "city": "Los Angeles", "state": "CA", "zip": "90001" },
    "items": [{
      "weight": 500,
      "freight_class": "70",
      "length": 48, "width": 40, "height": 48
    }]
  }'

Response:

{
  "object": "list",
  "url": "/v1/quotes",
  "data": [
    {
      "object": "quote",
      "id": 42,
      "carrier_name": "Sandbox Freight Co",
      "service_level": "Standard LTL",
      "net_charge_cents": 17500,
      "delivery_estimate": "3-5 business days",
      "expires_at": "2025-07-07T00:00:00.000Z"
    }
  ],
  "has_more": false
}

3. Book the shipment

curl -X POST https://api.freightcake.com/api/v1/shipments \
  -H "Authorization: Bearer fk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": 42,
    "ship_from": {
      "company": "Acme Corp",
      "contact": "Jane Doe",
      "address": "123 W Adams St",
      "city": "Chicago", "state": "IL", "zip": "60601",
      "phone": "312-555-0100"
    },
    "ship_to": {
      "company": "West Coast Warehouse",
      "contact": "John Smith",
      "address": "456 S Main St",
      "city": "Los Angeles", "state": "CA", "zip": "90001",
      "phone": "213-555-0200"
    }
  }'

4. Track the shipment

curl https://api.freightcake.com/api/v1/shipments/1/tracking \
  -H "Authorization: Bearer fk_test_your_key_here"

Want a deeper dive? The Walkthroughs section rebuilds each of the four steps above as full integration recipes — with TypeScript SDK examples, response shapes, common gotchas, and links to the underlying reference. Start with Rate shop an LTL shipment.

Core Concepts

Authentication

All API requests require a Bearer token. See Authentication for details.

Live vs. Test Mode

Every API request is either in live mode or test mode, determined by the API key prefix:

Key prefix	Mode	Description
`fk_live_`	Live	Real carrier rates and shipments
`fk_test_`	Test	Sandbox with mock carriers

Test and live data are completely isolated — test-mode keys can only see test-mode objects.

Response Format

All responses follow a consistent envelope:

{
  "object": "quote",
  "id": 42,
  ...fields
}

List endpoints use cursor-based pagination:

{
  "object": "list",
  "url": "/v1/quotes",
  "data": [...],
  "has_more": true
}

Error Handling

Errors return a structured error object:

{
  "error": {
    "type": "invalid_request_error",
    "message": "At least one item is required",
    "param": "items",
    "doc_url": "https://docs.freightcake.com/api/quotes"
  }
}

HTTP Status	Error Type
400	`invalid_request_error`
401	`authentication_error`
404	`not_found_error`
422	`unprocessable_entity_error`
429	`rate_limit_error`
500	`api_error`

Idempotency

POST requests support an Idempotency-Key header to safely retry operations:

curl -X POST .../v1/shipments \
  -H "Idempotency-Key: unique-request-id-123" \
  ...

The API caches the response for 24 hours. Retries with the same key return the cached response.

On this page