API Reference

The FreightFlow platform provides a high-performance REST interface for shipment management, container tracking, and terminal scraping orchestration.

---

1. Backend Core API

All core backend endpoints are prefixed with /api/v1 and generally require JWT Bearer Authorization unless specified otherwise.

Authentication & Users

Endpoint	Method	Description
/auth/jwt/login	POST	Exchange email and password for access token.
/login/microsoft	GET	Initiate Microsoft OAuth 2.0 flow.
/auth/callback	GET	Microsoft OAuth callback handler.
/users	GET	Retrieve list of registered users.

Organizations & Offices

Endpoint	Method	Description
/organizations	GET / POST	List all organizations or create a new one.
/organizations/{id}	GET / PATCH / DELETE	Retrieve, update, or remove an organization.
/offices	GET / POST	List all operational offices or create a new one.
/office/{office_id}	GET / PATCH / DELETE	Retrieve, update, or remove an office.

Shipments, Carriers & Terminals

Endpoint	Method	Description
/shipments	GET	List active shipments with search and filters.
/shipments/{shipment_id}	GET	Retrieve detailed shipment and container records.
/tai/{reference_number}	PATCH	Synchronize updates from TAI system manually.
/carriers	GET	Retrieve list of all available carriers.
/ports	GET	Retrieve list of all registered oceanic ports.
/terminals	GET	Retrieve list of tracking terminals.

Containers & Holds Tracking

Endpoint	Method	Description
/containers/mbl-grouped	GET	View tracking data grouped by Master Bill of Lading.
/containers/archived	GET	Fetch list of archived/completed containers.
/containers/{container_id}	GET / PATCH	Retrieve or update a specific container's timeline.
/containers/{container_id}/archive	POST	Manually mark a container as completed/archived.
/containers/{container_id}/scrape	POST	Dispatch manual background scrape for a single container.
/containers/bulk-scrape	POST	Dispatch tracking tasks for all active containers.
/containers/{container_id}/holds	POST	Register a new custom hold (Customs, USDA, etc.).
/containers/holds/{hold_id}	DELETE	Remove/release a registered hold.

Shipment Imports & Bulk Sync

Endpoint	Method	Description
/shipment-import/import-csv	POST	Upload a CSV file to bulk import missing shipments.
/shipment-import/import-sample-csv	GET	Download the CSV template for imports.
/shipment-import/import-status/{task_id}	GET	Check the background async status of an import task.
/shipment-import/trigger-sync	POST	Trigger bulk sync across Cargoes Flow.
/shipment-import/trigger-sync/{mbl_number}	POST	Force tracking sync for a specific Master Bill of Lading.
/shipment-import/create-carriers	POST	Register missing carriers flagged during imports.
/shipment-import/live	GET	Real-time import operational logs.
/shipment-import/map-routes/{shipment_number}	GET	Fetch geographic routing waypoints for the UI map.
/shipment-import/missing-mbl	GET	Identify shipments missing a valid tracking MBL.

Gravitas Management (New)

Base Path: /api/v1/gravitas

Endpoint	Method	Description	Auth Required
/gravitas/import	POST	Upload CSV file to import Gravitas shipments. Admin only.	JWT + Admin Role
/gravitas/containers	GET	List all tracked Gravitas containers with pagination.	JWT
/gravitas/containers/mbl-grouped	GET	View Gravitas containers grouped by MBL with KPI filtering.	JWT
/gravitas/shipments	GET	List all raw Gravitas shipment records.	JWT
/gravitas/shipments/{shipment_id}	GET	Retrieve specific Gravitas shipment details.	JWT
/gravitas/shipments/{shipment_id}/sync	POST	Force tracking sync for a specific shipment.	JWT
/gravitas/analytics/dashboard	GET	Get aggregated analytics for Gravitas dashboard.	JWT
/gravitas/containers/{container_id}	GET / PATCH	Retrieve or update a Gravitas container.	JWT
/gravitas/containers/{container_id}/scrape	POST	Trigger manual scraper for Gravitas container.	JWT

Gravitas CSV Import Format

The CSV import expects the following columns:

Column	Required	Description
File No.	No	Internal file reference number
MB/L No.	Yes	Master Bill of Lading (primary key)
Office	No	Operating office (defaults to "Gravitas")
Consignee	No	Consignee name
Oversea Agent	No	Overseas agent name
Container No.	No	Container number (optional, system discovers all containers via MBL)
Shipper	No	Shipper name

Import Process:

1. CSV uploaded via /gravitas/import
2. System creates/updates GravitasShipment by MBL
3. Syncs with Cargoes Flow to discover all containers under MBL
4. Creates GravitasContainer records for each container
5. Triggers terminal scrapers for LFD/LRD data

Gravitas KPI Filter Parameters

The /gravitas/containers/mbl-grouped endpoint supports KPI filtering:

Filter Value	Description
rail-shipments	Rail shipments only
manual-input-lfd	Containers needing manual LFD input
manual-input-lrd	Containers needing manual LRD input
demurrage-alert	Containers with demurrage risk
detention-alert	Containers with detention risk
lfd-alert	Containers needing fee input
pod-full-out	Full out from POD
pod-awaiting	Awaiting at POD
pod-need-attention	POD awaiting or full out
in-transit	In transit containers
arriving-today	Arriving today
delayed	Delayed containers
untrackable	Untrackable status

---

Analytics Dashboard

Endpoint	Method	Description
/analytics/dashboard	GET	Aggregate key performance indicators (KPIs) and summaries.

Webhooks (Internal Callback Logic)

NOTE

These endpoints consume data from other systems or microservices. They are secured via specialized X-API-TOKEN verification to prevent spoofing.

Endpoint	Method	Description
/webhook/tms	POST	Standardized payload ingestion from TAI TMS platform.
/webhooks/test	POST	Diagnostic endpoint for testing TMS webhook integration.
/webhooks/scraper	POST	Feedback loop that parses the final scraped data sent back from the Scraper workers.

---

2. Terminal Scraper API

The Scraper service runs in isolation, providing a gateway to various unstructured terminal portals. Authentication is strictly via the X-API-TOKEN header.

Common Tracking Pattern

All terminal routers respond to a simple JSON payload:

• Format: POST /terminal/scrape/{terminal_id}
• Payload: { "container_numbers": ["CONT1234567"] }

Supported Endpoints

Terminal / Port	Endpoint Path	Implementation Tech
PNCT (Port Newark)	/scrape/pnct	Legacy / API Priority
APM Terminals	/scrape/apm	API Based
APM Miami	/scrape/apm-miami	API Based
Maher Terminal	/scrape/maher	Selenium UI
Port Houston	/scrape/port-houston	API Based
Fenix Marine	/scrape/fenix-marine	Selenium UI
Yusen / YTI	/scrape/yusen	API Based
POMTOC	/scrape/pomtoc	API Based
eModal Platform	/scrape/emodal	API Based
Conley Terminal	/scrape/conley	API Based
Baltimore Seagirt	/scrape/baltimore-seagirt	API Based
Port of Savannah	/scrape/savannah	API Based
ITS Terminal	/scrape/its	API Based
ONE Carrier	/scrape/one	Dynamic Scrapling

Email Automation (Microsoft Outlook)

Endpoint	Method	Description
/email	POST	Consumes verification codes forwarded by MS PowerAutomate. Required when a terminal UI prompts for 2FA.

---

Security Context

CAUTION

Production Hardening: Ensure the Terminal Scraper instance limits incoming traffic solely to your Backend API's IP address.

JWT (User Facing)

• Header: Authorization: Bearer <TOKEN>
• Created when logging in via POST /api/v1/auth/jwt/login.
• Used to authenticate all frontend dashboard requests.

API Key (Service-to-Service)

• Header: X-API-TOKEN
• Sourced from .env variable SCRAPER_API_KEY.
• Used when Backend triggers a scrape task, and when Scraper answers back via Webhook.