# FreightPulse — full reference

> Real-time global logistics intelligence: fuel prices, freight rates, port congestion, supply-chain disruptions, and carrier lookups.
> Authentication: `X-API-Key: YOUR_KEY` or `Authorization: Bearer YOUR_KEY` header — BOTH optional (100 requests/day guest tier with neither).
> Base URL: `https://freightpulsehq.com/api/v1`
> Response shape is always `{"success": bool, "data": {...}}` on success, `{"success": false, "error": "..."}` on failure.

## GET /fuel-prices

Latest weekly average US diesel and gasoline prices by PADD region (EIA).

Example:
```
curl -H "X-API-Key: YOUR_KEY" "https://freightpulsehq.com/api/v1/fuel-prices"
```

MCP equivalent: tools/call with name="get_fuel_prices"

## GET /freight-rates

Trucking (ZIP-to-ZIP) or ocean/air quote from a limited set of Asian origins.

Parameters:
- `mode` (optional) — trucking (default), ocean, or air
- `origin_zip` (optional) — 5-digit US ZIP — required for mode=trucking
- `destination_zip` (optional) — 5-digit US ZIP — required for mode=trucking
- `origin_country` (optional) — ISO country code of the Asian origin — required for mode=ocean/air
- `dest_zip` (optional) — 5-digit US ZIP — required for mode=ocean/air

Example:
```
curl -H "X-API-Key: YOUR_KEY" "https://freightpulsehq.com/api/v1/freight-rates?mode=trucking&origin_zip=90001&destination_zip=10001"
```

MCP equivalent: tools/call with name="get_freight_rates"

## GET /port-congestion

Port-call activity vs. a 90-day baseline (IMF PortWatch). At least one of port/country/region is required.

Parameters:
- `port` (optional) — Port name
- `country` (optional) — Country name
- `region` (optional) — Region name
- `congestion` (optional) — low, moderate, or high

Example:
```
curl -H "X-API-Key: YOUR_KEY" "https://freightpulsehq.com/api/v1/port-congestion?port=Los+Angeles"
```

MCP equivalent: tools/call with name="get_port_congestion"

## GET /disruptions

Active natural-hazard disruptions (GDACS/USGS/NOAA). Geopolitics/strikes not covered.

Parameters:
- `type` (optional) — cyclone, earthquake, flood, volcano, drought, wildfire, or severe_weather
- `severity` (optional) — low, moderate, or high
- `country` (optional) — Country name
- `port` (optional) — Port name

Example:
```
curl -H "X-API-Key: YOUR_KEY" "https://freightpulsehq.com/api/v1/disruptions?type=cyclone&severity=high"
```

MCP equivalent: tools/call with name="get_disruptions"

## GET /carriers

US trucking carrier lookup (FMCSA) or ocean NVOCC/OTI lookup (FMC).

Parameters:
- `q` (optional) — Carrier name or DOT/organization number. Required unless type=ocean.
- `type` (optional) — trucking (default), ocean, or air (air not implemented yet)

Example:
```
curl -H "X-API-Key: YOUR_KEY" "https://freightpulsehq.com/api/v1/carriers?q=Werner&type=trucking"
```

MCP equivalent: tools/call with name="search_carriers"

## GET /historical

Historical weekly series for fuel prices or curated port-congestion metrics.

Parameters:
- `metric` (optional) — e.g. fuel_price_diesel_national. Default: fuel_price_diesel_national
- `period` (optional) — 30d, 90d, or 1y. Ignored if from/to given. Default: 30d
- `from` (optional) — Y-m-d, overrides period
- `to` (optional) — Y-m-d, >= from

Example:
```
curl -H "X-API-Key: YOUR_KEY" "https://freightpulsehq.com/api/v1/historical?metric=fuel_price_diesel_national&period=90d"
```

MCP equivalent: tools/call with name="get_historical_data"

## register (MCP tool only)

Chains POST /oauth/register + POST /oauth/token into one call. Args: client_name (required), contact_email (required). Returns an access_token usable as either Authorization: Bearer or X-API-Key, on the perpetual free tier (100 requests/month, 5/minute, no card). Rate-limited to 5 registrations/day per IP.

```
curl -X POST https://freightpulsehq.com/oauth/register -H "Content-Type: application/json" -d '{"client_name":"my-agent","contact_email":"you@example.com"}'
curl -X POST https://freightpulsehq.com/oauth/token -H "Content-Type: application/json" -d '{"grant_type":"client_credentials","client_id":"...","client_secret":"..."}'
```

## account_status (MCP tool only)

No args. Requires the key under test (Authorization or X-API-Key). Wraps GET /api/agents/health. Returns plan, monthly_quota, requests_used, remaining_requests, rate_limit_per_minute.