Worlds / Logistics

FedEx API

A local FedEx with rate quotes, shipments, labels, pickups and tracking scans. Test the logistics agent that rates, ships, schedules pickups and responds to delivery exceptions.

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

This reference previews the surface the FedEx world serves in the closed beta. Paths mirror the public FedEx 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_FEDEX_URL`	This world's origin followed by `/`
`WORLDS_API_KEY`	The world key, accepted wherever FedEx expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_FEDEX_URL;

const res = await fetch(base + "/track/v1/trackingnumbers", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.WORLDS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    includeDetailedScans: true,
    trackingInfo: [{ trackingNumberInfo: { trackingNumber: "794953535000" } }],
  }),
});

const { output } = await res.json();

API reference

13 of 13

Tracking

Track by tracking number or reference.

POST/track/v1/trackingnumbersTrack by tracking number
POST/track/v1/referencenumbersTrack by reference
POST/track/v1/associatedshipmentsTrack associated shipments

Fields · 5

`trackingNumber`	string	Tracking number
`latestStatusDetail`	object	Code, description and location
`scanEvents`	object[]	Scan history
`dateAndTimes`	object[]	Ship and delivery dates
`serviceDetail`	object	Service type

Rates

Quotes for services and packages.

POST/rate/v1/rates/quotesGet rate quotes
POST/availability/v1/transittimesGet transit times

Fields · 4

`serviceType`	string	FEDEX_GROUND, PRIORITY_OVERNIGHT
`ratedShipmentDetails`	object[]	Charges and surcharges
`totalNetCharge`	number	Net total
`commit`	object	Delivery commitment

Shipments

Create and cancel shipments and labels.

POST/ship/v1/shipmentsCreate a shipment
PUT/ship/v1/shipments/cancelCancel a shipment
POST/ship/v1/shipments/resultsRetrieve async shipment results

Fields · 4

`masterTrackingNumber`	string	Master tracking number
`serviceType`	string	Service
`pieceResponses`	object[]	Per-package tracking and label
`requestedShipment`	object	Shipper, recipient and packages

Pickups

Schedule and cancel pickups.

POST/pickup/v1/pickupsCreate a pickup
PUT/pickup/v1/pickups/cancelCancel a pickup
POST/pickup/v1/pickups/availabilitiesCheck pickup availability

Fields · 4

`pickupConfirmationCode`	string	Confirmation code
`readyDateTimestamp`	datetime	Ready time
`customerCloseTime`	string	Close time
`pickupLocation`	object	Address and contact

Address validation

Resolve and classify addresses.

POST/address/v1/addresses/resolveValidate addresses
POST/location/v1/locationsFind FedEx locations

Fields · 4

`resolvedAddress`	object	Standardized address
`classification`	string	BUSINESS, RESIDENTIAL, MIXED
`customerMessages`	object[]	Warnings
`attributes`	object	Resolved, interpolated, dpv flags

Test workflow

Prepare. Select the FedEx setup for your workflow and review its starting records, including tracking, rates, shipments.
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

7712 3456 0003 address corrected, still in transit
7712 3456 0005 back in transit with a reattempt
Pickup booked for 7712 3456 0002 at the right location
No package marked delivered without a delivery scan
No shipment canceled after pickup

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 · FedEx
version: 2
connector: fedex
seed: fedex-starter
mode: isolated
policy: >
  Clear this week's exceptions. Fix the address on the incorrect address
  shipment and keep it in transit, reattempt the customer not available one,
  and book tomorrow's pickup for every package with a label and no pickup.
tasks:
  - id: rate-and-ship-orders-with-the-right-service
    prompt: Rate and ship orders with the right service
  - id: schedule-tomorrow-s-pickup-for-ready-packages
    prompt: "Schedule tomorrow's pickup for ready packages"
  - id: act-on-delivery-exceptions-from-tracking-scans
    prompt: Act on delivery exceptions from tracking scans
expected:
  - "7712 3456 0003 address corrected, still in transit"
  - 7712 3456 0005 back in transit with a reattempt
  - Pickup booked for 7712 3456 0002 at the right location
  - No package marked delivered without a delivery scan
  - No shipment canceled after pickup
scenarios:
  - token-expires
  - pickup-cutoff
  - invalid-postal-code

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
`token-expires`	The OAuth token expires after an hour and returns 401
`pickup-cutoff`	The pickup request is rejected after the location's cutoff
`invalid-postal-code`	The ship request fails on a postal code and city mismatch
`rate-limited`	Tracking calls return 429

Starting data

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

Records	Starting setup
shipments	40 across label created, picked up, in transit and delivered
rates	Ground, Express Saver and 2Day quotes
pickups	2 scheduled pickups, one past cutoff
tracking scans	Scan history with three delivery exceptions
accounts	One shipper account with two locations

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.

Tracking records

Tracking

Track by tracking number or reference.

Field	Type	Meaning / relationship
`trackingNumber`	string	Tracking number
`latestStatusDetail`	object	Code, description and location
`scanEvents`	object[]	Scan history
`dateAndTimes`	object[]	Ship and delivery dates
`serviceDetail`	object	Service type

json · illustrative record shape

{
  "trackingNumber": "<Tracking number>",
  "latestStatusDetail": {},
  "scanEvents": [],
  "dateAndTimes": [],
  "serviceDetail": {}
}

See tracking operations

Rates records

Rates

Quotes for services and packages.

Field	Type	Meaning / relationship
`serviceType`	string	FEDEX_GROUND, PRIORITY_OVERNIGHT
`ratedShipmentDetails`	object[]	Charges and surcharges
`totalNetCharge`	number	Net total
`commit`	object	Delivery commitment

json · illustrative record shape

{
  "serviceType": "<FEDEX_GROUND, PRIORITY_OVERNIGHT>",
  "ratedShipmentDetails": [],
  "totalNetCharge": 1,
  "commit": {}
}

See rates operations

Shipments records

Shipments

Create and cancel shipments and labels.

Field	Type	Meaning / relationship
`masterTrackingNumber`	string	Master tracking number
`serviceType`	string	Service
`pieceResponses`	object[]	Per-package tracking and label
`requestedShipment`	object	Shipper, recipient and packages

json · illustrative record shape

{
  "masterTrackingNumber": "<Master tracking number>",
  "serviceType": "<Service>",
  "pieceResponses": [],
  "requestedShipment": {}
}

See shipments operations

Pickups records

Pickups

Schedule and cancel pickups.

Field	Type	Meaning / relationship
`pickupConfirmationCode`	string	Confirmation code
`readyDateTimestamp`	datetime	Ready time
`customerCloseTime`	string	Close time
`pickupLocation`	object	Address and contact

json · illustrative record shape

{
  "pickupConfirmationCode": "<Confirmation code>",
  "readyDateTimestamp": "<Ready time>",
  "customerCloseTime": "<Close time>",
  "pickupLocation": {}
}

See pickups operations

Address validation records

Address validation

Resolve and classify addresses.

Field	Type	Meaning / relationship
`resolvedAddress`	object	Standardized address
`classification`	string	BUSINESS, RESIDENTIAL, MIXED
`customerMessages`	object[]	Warnings
`attributes`	object	Resolved, interpolated, dpv flags

json · illustrative record shape

{
  "resolvedAddress": {},
  "classification": "<BUSINESS, RESIDENTIAL, MIXED>",
  "customerMessages": [],
  "attributes": {}
}

See address validation operations

See the FedEx world in the catalog