PortChief API — Developer Documentation

Manage container listings server-to-server over a small REST API: authenticate once, then create, read, search, update and withdraw listings.

Base URL  https://portchief.com/wp-json/portchief/v1

ℹ️ The examples below use the full URL (with https:// and the host) — copy-paste them as-is, nothing to concatenate.

🚀 Quick start

1. Exchange your PortChief credentials for a token at POST /auth/token.
2. Send that token as Authorization: Bearer <token> on every call.
3. Create listings with POST /listings.
4. Read, search, update or withdraw them with GET / PATCH / DELETE /listings. Done.

1 · Authentication

Exchange a WordPress username + password for a signed JWT. The token is valid 30 days.

Request

POST https://portchief.com/wp-json/portchief/v1/auth/token
Content-Type: application/json

{
  "username": "your-account",
  "password": "your-password"
}

Response · 200 OK

{
  "token": "eyJhbGciOiJIUzI1Ni␣...",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "user": { "id": 4, "email": "you@example.com", "name": "Your Name" }
}

Bad credentials return 401 { "code": "pc_auth_failed" }.

Using the token

Authorization: Bearer eyJhbGciOiJIUzI1Ni␣...

2 · Create a listing

Creates one published container listing. One listing = one container (atomic). Your organization is taken from your account — never from the payload.

Required fields

Optional fields

Example request

POST https://portchief.com/wp-json/portchief/v1/listings
Authorization: Bearer <token>
Content-Type: application/json

{
  "direction": "offer",
  "container_type": "40HC",
  "city": "marseille-fos",
  "lat": 43.34, "lng": 4.99,
  "description": "Reefer-ready 40HC, clean box.",
  "pickup_window": { "start": "2026-06-20", "end": "2026-06-30" },
  "price": 150
}

Response · 201 Created

{
  "id": 659463,
  "url": "https://portchief.com/listing/offre-40hc-marseille-fos/",
  "status": "publish"
}

3 · Read a listing

Returns the full, enriched view of any published listing (so you can confirm what the server stored and reconcile your own system).

GET https://portchief.com/wp-json/portchief/v1/listings/659463
Authorization: Bearer <token>

Response · 200 OK

{
  "id": 659463,
  "url": "https://portchief.com/listing/offre-40hc-marseille-fos/",
  "status": "publish",
  "direction": "offer",
  "title": "Offre — 40HC · Marseille-Fos",
  "city": { "slug": "marseille-fos", "name": "Marseille-Fos" },
  "container_type": { "slug": "40-hc", "label": "40HC" },
  "coords": { "lat": 43.34, "lng": 4.99 },
  "pickup_window": { "start": "2026-06-20", "end": "2026-06-30" },
  "price": 150,
  "contact": { "email": "you@example.com", "phone": null, "website": null },
  "created_at": "2026-06-16T12:57:31+02:00",
  "updated_at": "2026-06-17T09:49:00+02:00"
}

Unknown / withdrawn id returns 404 { "code": "pc_not_found" }.

4 · Search listings

List and filter listings. Parameters go in the URL query string (a GET has no body): ?key=value&key2=value2.

GET https://portchief.com/wp-json/portchief/v1/listings?direction=need&container_type=reefer&lat=43.34&lng=4.99&radius_km=50
Authorization: Bearer <token>

Response · 200 OK

{
  "results": [ { /* same shape as “Read a listing” */ "distance_km": 12.3 } ],
  "page": 1, "per_page": 20, "total": 7, "total_pages": 1
}

distance_km (km, 1 decimal) is included only in proximity search (lat+lng+radius_km) — plain searches and Read a listing don’t have it.

5 · Update a listing

Update one of your own listings (others return 403). Send only the fields you want to change; the listing id stays stable.

PATCH https://portchief.com/wp-json/portchief/v1/listings/659463
Authorization: Bearer <token>
Content-Type: application/json

{
  "pickup_window": { "start": "2026-07-01" }
}

Returns 200 with the updated listing (same shape as “Read”). Invalid fields → 400 with data.fields. Note: switching an offer to need drops its price.

6 · Withdraw a listing

Withdraw one of your own listings once the container is gone — it immediately disappears from the marketplace. Soft delete (recoverable), and idempotent: calling it again still returns 200.

DELETE https://portchief.com/wp-json/portchief/v1/listings/659463
Authorization: Bearer <token>

Response · 200 OK

{ "id": 659463, "status": "withdrawn" }

7 · Errors

Validation error example · 400

{
  "code": "pc_validation",
  "message": "Invalid listing payload.",
  "data": {
    "status": 400,
    "fields": {
      "pickup_window.start": "Invalid date '20226'. Use strict ISO 8601 YYYY-MM-DD."
    }
  }
}

Notes

• Versioning — the API is namespaced /v1. New optional fields may be added without breaking changes; any breaking change ships under a new version.
• Quantity — fixed at 1 per listing. To post N containers, send N requests.
• Contact — buyers reach you through the contact details on your organization profile.