Worlds / Logistics

project44 API

A local project44 with tracked shipments, stops, carrier events, predicted ETAs and exceptions. Test the visibility agent that monitors loads, flags delays and updates customers.

Base path: /api/v4
Auth: OAuth 2.0 client credentials bearer token, the world key
Endpoints: 13
Status: Active today

This reference previews the surface the project44 world serves in the closed beta. Paths mirror the public project44 API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_PROJECT44_URL`	This world's origin followed by `/api/v4`
`WORLDS_API_KEY`	The world key, accepted wherever project44 expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_PROJECT44_URL + "/api/v4";

const res = await fetch(base + "/shipments/tracking", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.WORLDS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    carrierIdentifier: { type: "SCAC", value: "FDEG" },
    shipmentIdentifiers: [{ type: "BILL_OF_LADING", value: "BOL-77120" }],
  }),
});

const shipment = await res.json();

API reference

13 of 13

Shipments

Tracked truckload and LTL shipments.

POST/api/v4/shipments/trackingCreate a tracked shipment
GET/api/v4/shipments/{shipmentId}Get a shipment
PUT/api/v4/shipments/{shipmentId}Update a shipment
DELETE/api/v4/shipments/{shipmentId}Stop tracking a shipment
GET/api/v4/shipments/{shipmentId}/statusesList status events

Fields · 5

`shipmentId`	integer	project44 shipment id
`shipmentIdentifiers`	object[]	BOL, PRO and PO numbers
`carrierIdentifier`	object	SCAC or DOT number
`shipmentStops`	object[]	Pickup and delivery stops
`latestStatus`	object	Latest status event

Ocean shipments

Container and booking visibility.

POST/api/v4/ocean/shipmentsCreate an ocean shipment
GET/api/v4/ocean/shipments/{shipmentId}Get an ocean shipment
GET/api/v4/ocean/shipments/{shipmentId}/eventsList ocean events

Fields · 5

`shipmentId`	string	Shipment id
`containerNumber`	string	Container number
`billOfLadingNumber`	string	Bill of lading
`vessel`	object	Vessel name and IMO
`portCalls`	object[]	Port events and ETAs

Rate quotes

Spot and contract LTL quotes.

POST/api/v4/ltl/quotes/rates/queryGet LTL rate quotes
POST/api/v4/ltl/shipments/dispatchDispatch an LTL shipment
POST/api/v4/ltl/bol/documentsCreate a bill of lading

Fields · 5

`quoteId`	string	Quote id
`originAddress`	object	Origin
`destinationAddress`	object	Destination
`lineItems`	object[]	Freight class and weight
`rateQuotes`	object[]	Carrier quotes

Capacity providers

Carriers the account is connected to.

GET/api/v4/capacityprovidersList capacity providers
GET/api/v4/capacityproviders/{carrierId}Get a capacity provider

Fields · 4

`capacityProviderAccountGroup`	object	Account group
`carrierName`	string	Carrier name
`scac`	string	SCAC
`status`	string	Connected or pending

Test workflow

Prepare. Select the project44 setup for your workflow and review its starting records, including shipments, ocean shipments, rate quotes.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

SH-90211 flagged late with a customer note
SH-90212 exception still open, no new carrier position
SH-90213 resolved after a newer carrier event
No shipment closed without a delivery event
SH-90214 not flagged, it is on time

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · project44
version: 2
connector: project44
seed: project44-starter
mode: isolated
policy: >
  Review at risk shipments. Flag any load whose ETA misses its delivery window
  and tell the customer, resolve exceptions only when the carrier has sent a
  newer event, and close nothing that is not delivered.
tasks:
  - id: flag-shipments-whose-eta-misses-the-delivery-window
    prompt: Flag shipments whose ETA misses the delivery window
  - id: resolve-exceptions-with-carrier-updates
    prompt: Resolve exceptions with carrier updates
  - id: close-out-delivered-shipments
    prompt: Close out delivered shipments
expected:
  - SH-90211 flagged late with a customer note
  - "SH-90212 exception still open, no new carrier position"
  - SH-90213 resolved after a newer carrier event
  - No shipment closed without a delivery event
  - "SH-90214 not flagged, it is on time"
scenarios:
  - tracking-lost
  - eta-flips
  - events-out-of-order

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`tracking-lost`	No position pings for six hours on one load
`eta-flips`	The predicted ETA changes between two reads
`events-out-of-order`	An arrival event lands before the departure event
`rate-limited`	Shipment queries return 429
`token-expires`	The OAuth token returns 401 mid run

Starting data

Start each run from the same records and relationships. The overview below describes the project44 starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
shipments	60 truckload and LTL shipments
stops	Pickup and delivery stops with appointment windows
carrier events	Ping history, arrivals and departures
ETAs	Predicted arrival per stop, eight late
exceptions	Missed pickup, tracking lost and delay

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Shipments records

Shipments

Tracked truckload and LTL shipments.

Field	Type	Meaning / relationship
`shipmentId`	integer	project44 shipment id
`shipmentIdentifiers`	object[]	BOL, PRO and PO numbers
`carrierIdentifier`	object	SCAC or DOT number
`shipmentStops`	object[]	Pickup and delivery stops
`latestStatus`	object	Latest status event

json · illustrative record shape

{
  "shipmentId": 1,
  "shipmentIdentifiers": [],
  "carrierIdentifier": {},
  "shipmentStops": [],
  "latestStatus": {}
}

See shipments operations

Ocean shipments records

Ocean shipments

Container and booking visibility.

Field	Type	Meaning / relationship
`shipmentId`	string	Shipment id
`containerNumber`	string	Container number
`billOfLadingNumber`	string	Bill of lading
`vessel`	object	Vessel name and IMO
`portCalls`	object[]	Port events and ETAs

json · illustrative record shape

{
  "shipmentId": "<Shipment id>",
  "containerNumber": "<Container number>",
  "billOfLadingNumber": "<Bill of lading>",
  "vessel": {},
  "portCalls": []
}

See ocean shipments operations

Rate quotes records

Rate quotes

Spot and contract LTL quotes.

Field	Type	Meaning / relationship
`quoteId`	string	Quote id
`originAddress`	object	Origin
`destinationAddress`	object	Destination
`lineItems`	object[]	Freight class and weight
`rateQuotes`	object[]	Carrier quotes

json · illustrative record shape

{
  "quoteId": "<Quote id>",
  "originAddress": {},
  "destinationAddress": {},
  "lineItems": [],
  "rateQuotes": []
}

See rate quotes operations

Capacity providers records

Capacity providers

Carriers the account is connected to.

Field	Type	Meaning / relationship
`capacityProviderAccountGroup`	object	Account group
`carrierName`	string	Carrier name
`scac`	string	SCAC
`status`	string	Connected or pending

json · illustrative record shape

{
  "capacityProviderAccountGroup": {},
  "carrierName": "<Carrier name>",
  "scac": "<SCAC>",
  "status": "<Connected or pending>"
}

See capacity providers operations

See the project44 world in the catalog