Worlds / Logistics

EasyPost API

A local EasyPost with addresses, shipments, rates, insurance, refunds and trackers. Test the shipping agent that verifies addresses, buys postage, insures parcels and handles returns.

Base path: /v2
Auth: HTTP basic with API key as username, the world key
Endpoints: 19
Status: Active today

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

js · @easypost/api

import EasyPost from "@easypost/api";

const client = new EasyPost(process.env.WORLDS_API_KEY, {
  baseUrl: process.env.WORLDS_EASYPOST_URL + "/v2/",
});

const shipment = await client.Shipment.create({
  to_address: { name: "Ada Lee", street1: "965 Mission St", city: "San Francisco", state: "CA", zip: "94103", country: "US" },
  from_address: { name: "Sparta", street1: "215 Clayton St", city: "San Francisco", state: "CA", zip: "94117", country: "US" },
  parcel: { length: 10, width: 8, height: 4, weight: 32 },
});

API reference

19 of 19

Addresses

Create and verify addresses.

POST/v2/addressesCreate an address
GET/v2/addresses/{id}Retrieve an address
GET/v2/addressesList addresses
POST/v2/addresses/create_and_verifyCreate and verify an address

Fields · 6

`id`	string	Address id, adr_
`street1`	string	Street line 1
`city`	string	City
`state`	string	State
`zip`	string	Postal code
`verifications`	object	Delivery verification results

Shipments

Shipments, rates and label purchase.

POST/v2/shipmentsCreate a shipment
GET/v2/shipments/{id}Retrieve a shipment
GET/v2/shipmentsList shipments
POST/v2/shipments/{id}/buyBuy a shipment label
POST/v2/shipments/{id}/refundRefund a shipment

Fields · 6

`id`	string	Shipment id, shp_
`rates`	object[]	Carrier rates
`selected_rate`	object	Purchased rate
`postage_label`	object	Label urls
`tracking_code`	string	Tracking code
`status`	string	Shipment status

Trackers

Track a package by code and carrier.

POST/v2/trackersCreate a tracker
GET/v2/trackers/{id}Retrieve a tracker
GET/v2/trackersList trackers

Fields · 6

`id`	string	Tracker id, trk_
`tracking_code`	string	Tracking code
`carrier`	string	Carrier
`status`	string	pre_transit, in_transit, delivered
`tracking_details`	object[]	Scan events
`est_delivery_date`	datetime	Estimated delivery

Pickups

Schedule carrier pickups.

POST/v2/pickupsCreate a pickup
POST/v2/pickups/{id}/buyBuy a pickup
POST/v2/pickups/{id}/cancelCancel a pickup

Fields · 5

`id`	string	Pickup id, pickup_
`status`	string	unknown, scheduled, canceled
`min_datetime`	datetime	Earliest pickup
`max_datetime`	datetime	Latest pickup
`pickup_rates`	object[]	Available pickup rates

Batches

Buy many labels at once.

POST/v2/batchesCreate a batch
GET/v2/batches/{id}Retrieve a batch
POST/v2/batches/{id}/buyBuy a batch
POST/v2/batches/{id}/labelGenerate batch labels

Fields · 4

`id`	string	Batch id, batch_
`state`	string	creating, purchased, label_generated
`num_shipments`	integer	Shipment count
`shipments`	object[]	Shipments in the batch

Test workflow

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

shp_a1 purchased with $320 insurance
shp_a2 not purchased, its address failed verification
shp_a3 purchased with one label
No parcel over $200 shipped without insurance
No duplicate labels on any shipment

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 · EasyPost
version: 2
connector: easypost
seed: easypost-starter
mode: isolated
policy: >
  Buy postage for today's shipments. Verify every address first and hold any
  that fail, insure parcels over $200 for their declared value, and do not buy
  duplicate labels.
tasks:
  - id: verify-addresses-before-buying-postage
    prompt: Verify addresses before buying postage
  - id: insure-high-value-shipments
    prompt: Insure high value shipments
  - id: create-return-labels-for-approved-returns
    prompt: Create return labels for approved returns
expected:
  - shp_a1 purchased with $320 insurance
  - "shp_a2 not purchased, its address failed verification"
  - shp_a3 purchased with one label
  - No parcel over $200 shipped without insurance
  - No duplicate labels on any shipment
scenarios:
  - address-check-fails
  - postage-purchase-fails
  - refund-rejected

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
`address-check-fails`	ADDRESS.VERIFY.FAILURE on strict verification
`postage-purchase-fails`	The buy call returns a carrier error for an oversized parcel
`refund-rejected`	The refund comes back rejected because the label was scanned
`rate-limited`	Shipment creates return 429
`webhook-twice`	tracker.updated arrives two times

Starting data

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

Records	Starting setup
addresses	60, eight that fail verification
shipments	45 across unpurchased, purchased and returned
insurance	Policies on 10 shipments over $200
refunds	5 across submitted, refunded and rejected
trackers	Across pre_transit, in_transit, out_for_delivery and delivered

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.

Addresses records

Addresses

Create and verify addresses.

Field	Type	Meaning / relationship
`id`	string	Address id, adr_
`street1`	string	Street line 1
`city`	string	City
`state`	string	State
`zip`	string	Postal code
`verifications`	object	Delivery verification results

json · illustrative record shape

{
  "id": "<Address id, adr_>",
  "street1": "<Street line 1>",
  "city": "<City>",
  "state": "<State>",
  "zip": "<Postal code>",
  "verifications": {}
}

See addresses operations

Shipments records

Shipments

Shipments, rates and label purchase.

Field	Type	Meaning / relationship
`id`	string	Shipment id, shp_
`rates`	object[]	Carrier rates
`selected_rate`	object	Purchased rate
`postage_label`	object	Label urls
`tracking_code`	string	Tracking code
`status`	string	Shipment status

json · illustrative record shape

{
  "id": "<Shipment id, shp_>",
  "rates": [],
  "selected_rate": {},
  "postage_label": {},
  "tracking_code": "<Tracking code>",
  "status": "<Shipment status>"
}

See shipments operations

Trackers records

Trackers

Track a package by code and carrier.

Field	Type	Meaning / relationship
`id`	string	Tracker id, trk_
`tracking_code`	string	Tracking code
`carrier`	string	Carrier
`status`	string	pre_transit, in_transit, delivered
`tracking_details`	object[]	Scan events
`est_delivery_date`	datetime	Estimated delivery

json · illustrative record shape

{
  "id": "<Tracker id, trk_>",
  "tracking_code": "<Tracking code>",
  "carrier": "<Carrier>",
  "status": "<pre_transit, in_transit, delivered>",
  "tracking_details": [],
  "est_delivery_date": "<Estimated delivery>"
}

See trackers operations

Pickups records

Pickups

Schedule carrier pickups.

Field	Type	Meaning / relationship
`id`	string	Pickup id, pickup_
`status`	string	unknown, scheduled, canceled
`min_datetime`	datetime	Earliest pickup
`max_datetime`	datetime	Latest pickup
`pickup_rates`	object[]	Available pickup rates

json · illustrative record shape

{
  "id": "<Pickup id, pickup_>",
  "status": "<unknown, scheduled, canceled>",
  "min_datetime": "<Earliest pickup>",
  "max_datetime": "<Latest pickup>",
  "pickup_rates": []
}

See pickups operations

Batches records

Batches

Buy many labels at once.

Field	Type	Meaning / relationship
`id`	string	Batch id, batch_
`state`	string	creating, purchased, label_generated
`num_shipments`	integer	Shipment count
`shipments`	object[]	Shipments in the batch

json · illustrative record shape

{
  "id": "<Batch id, batch_>",
  "state": "<creating, purchased, label_generated>",
  "num_shipments": 1,
  "shipments": []
}

See batches operations

See the EasyPost world in the catalog