Worlds / Logistics

UPS API

A local UPS with shipments, labels, tracking activity, delivery windows and address validation. Test the customer service agent that tracks packages, changes deliveries and files returns.

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

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

js · fetch

const base = process.env.WORLDS_UPS_URL + "/api";

const res = await fetch(base + "/track/v1/details/1Z999AA10123456784?locale=en_US", {
  headers: {
    Authorization: "Bearer " + process.env.WORLDS_API_KEY,
    transId: "agent-001",
    transactionSrc: "sparta",
  },
});

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

API reference

13 of 13

Tracking

Package tracking details.

GET/api/track/v1/details/{inquiryNumber}Get tracking details
GET/api/track/v1/reference/details/{referenceNumber}Track by reference

Fields · 5

`trackingNumber`	string	1Z tracking number
`package`	object[]	Package activity and status
`currentStatus`	object	Description and code
`deliveryDate`	object[]	Scheduled or actual date
`activity`	object[]	Scan events

Rating

Rates and transit estimates.

POST/api/rating/v2205/RateGet a rate for one service
POST/api/rating/v2205/ShopCompare all services
POST/api/shipments/v1/transittimesGet time in transit

Fields · 4

`Service`	object	Service code
`TotalCharges`	object	Currency and amount
`GuaranteedDelivery`	object	Guaranteed days
`RatedPackage`	object[]	Per-package charges

Shipping

Create and void shipments and labels.

POST/api/shipments/v2205/shipCreate a shipment
DELETE/api/shipments/v2205/void/cancel/{shipmentidentificationnumber}Void a shipment
POST/api/labels/v1/recoveryRecover a label

Fields · 4

`ShipmentIdentificationNumber`	string	Shipment id
`PackageResults`	object[]	Tracking number and label
`ShipmentCharges`	object	Charge breakdown
`ShipTo`	object	Recipient

Address validation

Street-level address checks.

POST/api/addressvalidation/v2/{requestoption}Validate an address
POST/api/locations/v2/search/availabilities/{reqOption}Find access point locations

Fields · 4

`ValidAddressIndicator`	string	Address is valid
`AmbiguousAddressIndicator`	string	Several matches
`Candidate`	object[]	Suggested addresses
`AddressClassification`	object	Commercial or residential

Pickups

Schedule and cancel pickups.

POST/api/shipments/v1/pickup/{pickuptype}Create a pickup
DELETE/api/shipments/v1/pickup/{CancelBy}Cancel a pickup
GET/api/shipments/v1/pickup/pendingList pending pickups

Fields · 5

`PRN`	string	Pickup request number
`PickupDate`	string	Pickup date, YYYYMMDD
`ReadyTime`	string	Ready time
`CloseTime`	string	Close time
`PickupAddress`	object	Pickup address

Test workflow

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

1Z999AA10123456781 held at the nearest access point
1Z999AA10123456782 redirected to the work address
No change requested on 1Z999AA10123456783, it was delivered
Return created for 1Z999AA10123456785 linked to its original
No delivery change on a package out for delivery

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 · UPS
version: 2
connector: ups
seed: ups-starter
mode: isolated
policy: >
  Work the open inquiries. Hold or redirect packages only while they are still
  in transit, explain the exception on the stuck one, and create returns for
  approved requests only.
tasks:
  - id: answer-where-is-my-package-with-tracking-activity
    prompt: Answer where is my package with tracking activity
  - id: redirect-or-hold-packages-before-delivery
    prompt: Redirect or hold packages before delivery
  - id: create-return-shipments-for-approved-returns
    prompt: Create return shipments for approved returns
expected:
  - 1Z999AA10123456781 held at the nearest access point
  - 1Z999AA10123456782 redirected to the work address
  - "No change requested on 1Z999AA10123456783, it was delivered"
  - Return created for 1Z999AA10123456785 linked to its original
  - No delivery change on a package out for delivery
scenarios:
  - token-expires
  - change-not-allowed
  - tracking-not-found

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 access token returns 401 mid run
`change-not-allowed`	A delivery change is refused once the package is out for delivery
`tracking-not-found`	A new label returns no tracking activity yet
`rate-limited`	Tracking calls return 429

Starting data

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

Records	Starting setup
shipments	50 with 1Z tracking numbers
tracking	Activity across label created, in transit, out for delivery, delivered and exception
delivery windows	Estimated windows on out for delivery packages
addresses	Shipper and consignee addresses, some residential
returns	6 approved return requests

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

Package tracking details.

Field	Type	Meaning / relationship
`trackingNumber`	string	1Z tracking number
`package`	object[]	Package activity and status
`currentStatus`	object	Description and code
`deliveryDate`	object[]	Scheduled or actual date
`activity`	object[]	Scan events

json · illustrative record shape

{
  "trackingNumber": "<1Z tracking number>",
  "package": [],
  "currentStatus": {},
  "deliveryDate": [],
  "activity": []
}

See tracking operations

Rating records

Rating

Rates and transit estimates.

Field	Type	Meaning / relationship
`Service`	object	Service code
`TotalCharges`	object	Currency and amount
`GuaranteedDelivery`	object	Guaranteed days
`RatedPackage`	object[]	Per-package charges

json · illustrative record shape

{
  "Service": {},
  "TotalCharges": {},
  "GuaranteedDelivery": {},
  "RatedPackage": []
}

See rating operations

Shipping records

Shipping

Create and void shipments and labels.

Field	Type	Meaning / relationship
`ShipmentIdentificationNumber`	string	Shipment id
`PackageResults`	object[]	Tracking number and label
`ShipmentCharges`	object	Charge breakdown
`ShipTo`	object	Recipient

json · illustrative record shape

{
  "ShipmentIdentificationNumber": "<Shipment id>",
  "PackageResults": [],
  "ShipmentCharges": {},
  "ShipTo": {}
}

See shipping operations

Address validation records

Address validation

Street-level address checks.

Field	Type	Meaning / relationship
`ValidAddressIndicator`	string	Address is valid
`AmbiguousAddressIndicator`	string	Several matches
`Candidate`	object[]	Suggested addresses
`AddressClassification`	object	Commercial or residential

json · illustrative record shape

{
  "ValidAddressIndicator": "<Address is valid>",
  "AmbiguousAddressIndicator": "<Several matches>",
  "Candidate": [],
  "AddressClassification": {}
}

See address validation operations

Pickups records

Pickups

Schedule and cancel pickups.

Field	Type	Meaning / relationship
`PRN`	string	Pickup request number
`PickupDate`	string	Pickup date, YYYYMMDD
`ReadyTime`	string	Ready time
`CloseTime`	string	Close time
`PickupAddress`	object	Pickup address

json · illustrative record shape

{
  "PRN": "<Pickup request number>",
  "PickupDate": "<Pickup date, YYYYMMDD>",
  "ReadyTime": "<Ready time>",
  "CloseTime": "<Close time>",
  "PickupAddress": {}
}

See pickups operations

See the UPS world in the catalog