> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primefreight.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> PrimeFreight Tracking API - Ocean freight shipment tracking

# PrimeFreight Tracking API

PrimeFreight offers a tracking API that enables businesses to monitor ocean freight shipments. This API provides access to shipment information and status updates from shipping lines.

## What the API Does

* **Create tracking requests**
  * Use bill of lading or container numbers
  * Provide carrier SCAC
  * Kick off shipment tracking

* **Retrieve tracking information**
  * Check tracking request status
  * Access shipment data when available
  * View request details

* **Receive webhook notifications**
  * Real-time success/failure updates
  * Shipment changes and status updates

* **Get container details**
  * Status, terminal info, relationships
  * Availability, last free day, rail metadata (when available)

* **Get container raw events**
  * Past and future (estimated) milestones from carriers
  * Original carrier event text with normalized event/timestamp fields

* **Get container transport events**
  * Vetted, normalized milestones for reliable timelines
  * Reduced false positives with standardized event types

## Authentication

Before calling other endpoints, obtain an access token.

* Endpoint: `POST /auth/tokens`
* Headers: `Content-Type: application/json`
* Body (JSON): `{ "username": "primefreight", "password": "pass123" }`

Example request:

```bash theme={null}
curl -X POST \
  https://api.primefreight.com/auth/tokens \
  -H 'Content-Type: application/json' \
  -d '{"username":"primefreight","password":"pass123"}'
```

Use the returned token in the `Authorization` header for subsequent requests:

```bash theme={null}
curl https://api.primefreight.com/tracking_requests/{id} \
  -H 'Authorization: Bearer <token>'
```

## API Architecture

The API follows RESTful principles with JSON:API specification for consistent data formatting. All endpoints require authentication using bearer tokens.

### Core Endpoints

1. **POST /auth/tokens** - Obtain an access token
2. **POST /tracking\_requests** - Create a new tracking request
3. **GET /tracking\_requests/{id}** - Retrieve tracking request details
4. **GET /containers/{id}** - Retrieve container details
5. **GET /containers/{id}/raw\_events** - Retrieve container raw events
6. **GET /containers/{id}/transport\_events** - Retrieve container transport events
7. **Webhooks** - Receive real-time status notifications

## Technical Specifications

* **API Version**: v1
* **Base URL**: `https://api.primefreight.com`
* **Data Format**: JSON:API specification
* **Authentication**: Bearer token via `Authorization` header
* **Webhook Support**: Real-time event notifications

## Use Cases

The PrimeFreight Tracking API serves basic tracking needs:

### Shipment Monitoring

* Track individual shipments using available identifiers
* Monitor tracking request status
* Receive notifications about tracking results

### Integration

* Integrate tracking capabilities into existing systems
* Build custom tracking interfaces
* Automate tracking request creation