REST API Reference

The Freigent REST API provides programmatic access to all platform functionality. All API endpoints use HTTPS and require authentication.

Base URL

https://api.freigent.ai/v1

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Rate Limits

• Standard Plan: 1,000 requests per hour
• Pro Plan: 10,000 requests per hour
• Enterprise: Custom limits

Response Format

All responses are in JSON format:

{
  "success": true,
  "data": {...},
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150
  }
}

Error Handling

Error responses include status codes and detailed messages:

{
  "success": false,
  "error": {
    "code": "INVALID_LOAD",
    "message": "Load not found",
    "details": {...}
  }
}

Loads API

Create Load

POST /loads

Request Body:

{
  "origin": {
    "city": "Chicago",
    "state": "IL",
    "zip": "60601",
    "address": "123 Main St"
  },
  "destination": {
    "city": "Atlanta",
    "state": "GA", 
    "zip": "30301",
    "address": "456 Oak Ave"
  },
  "weight": 25000,
  "equipment_type": "dry_van",
  "pickup_date": "2024-12-01T08:00:00Z",
  "delivery_date": "2024-12-03T17:00:00Z",
  "rate": 2500.00,
  "notes": "Fragile items, handle with care"
}

Response:

{
  "success": true,
  "data": {
    "id": "load_123abc",
    "status": "posted",
    "origin": {...},
    "destination": {...},
    "weight": 25000,
    "equipment_type": "dry_van",
    "created_at": "2024-11-15T10:30:00Z"
  }
}

Get Load

GET /loads/{load_id}

Response:

{
  "success": true,
  "data": {
    "id": "load_123abc",
    "status": "in_transit",
    "origin": {...},
    "destination": {...},
    "carrier": {
      "id": "carrier_456def",
      "name": "ABC Trucking",
      "mc_number": "123456"
    },
    "tracking": {
      "current_location": {
        "lat": 39.7684,
        "lng": -86.1581,
        "city": "Indianapolis",
        "state": "IN"
      },
      "eta": "2024-12-03T15:30:00Z",
      "last_update": "2024-12-02T14:20:00Z"
    }
  }
}

List Loads

GET /loads?page=1&limit=50&status=posted

Query Parameters:

• page - Page number (default: 1)
• limit - Items per page (default: 50, max: 100)
• status - Filter by status: posted, assigned, in_transit, delivered
• origin_state - Filter by origin state
• destination_state - Filter by destination state

Update Load Status

PATCH /loads/{load_id}/status

Request Body:

{
  "status": "in_transit",
  "location": {
    "lat": 39.7684,
    "lng": -86.1581
  },
  "notes": "Picked up at 08:15 AM"
}

Carriers API

List Carriers

GET /carriers

Get Carrier Details

GET /carriers/{carrier_id}

Create Carrier

POST /carriers

Request Body:

{
  "name": "ABC Trucking Company",
  "mc_number": "123456",
  "dot_number": "654321", 
  "contact": {
    "email": "dispatch@abctrucking.com",
    "phone": "+1-555-123-4567"
  },
  "equipment_types": ["dry_van", "refrigerated"],
  "service_areas": ["IL", "IN", "OH", "MI"]
}

Tracking API

Get Real-time Location

GET /loads/{load_id}/tracking

Update Location

POST /loads/{load_id}/tracking

Request Body:

{
  "lat": 39.7684,
  "lng": -86.1581,
  "timestamp": "2024-12-02T14:20:00Z",
  "speed": 65,
  "heading": 90
}

Webhooks

Configure Webhook

POST /webhooks

Request Body:

{
  "url": "https://your-app.com/webhook",
  "events": ["load.created", "load.status_changed", "tracking.updated"],
  "secret": "your_webhook_secret"
}

Webhook Events

• load.created - New load posted
• load.assigned - Load assigned to carrier
• load.status_changed - Load status updated
• tracking.updated - GPS location updated
• delivery.completed - Load delivered

Status Codes

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 429 - Rate Limited
• 500 - Internal Server Error

SDK Examples

JavaScript/Node.js

const FreigentAPI = require('@freigent/api');

const client = new FreigentAPI({
  apiKey: 'your_api_key_here'
});

// Create a load
const load = await client.loads.create({
  origin: { city: 'Chicago', state: 'IL', zip: '60601' },
  destination: { city: 'Atlanta', state: 'GA', zip: '30301' },
  weight: 25000,
  equipment_type: 'dry_van'
});

console.log('Load created:', load.id);

Python

import freigent

client = freigent.Client(api_key='your_api_key_here')

# Get load details
load = client.loads.get('load_123abc')
print(f"Load status: {load.status}")

# Update tracking
client.tracking.update('load_123abc', {
    'lat': 39.7684,
    'lng': -86.1581
})