Reference · v1
REST surface for vehicle catalog, auction pricing, FX, container packing, HTS, duty schedules, vessel tracking, and battery state-of-health. Read-only except where noted.
Every /api/v1/* request carries an X-WATTSHIP-KEY header. Keys are stored as SHA-256 hashes — the raw key is shown only once at generation. Generate yours in Dashboard → Settings → API Access.
curl https://wattship.xyz/api/v1/vehicles?type=kei&limit=5 \
-H "X-WATTSHIP-KEY: wsk_live_..."
Indicative ceiling: 1,000 requests per day per API key. Usage is recorded in api_usage on every call so we can tune as real-world load lands.
/api/v1/vehicles Merged EV + Kei catalog with type / make / country_legal filters and pagination.
type ev | kei — Restrict to one catalog. make string — Case-insensitive equality. country_legal iso-2 — Vehicles legal in the given country. limit int (1-50) — Default 20. offset int — Default 0. { data: { vehicles[], total, limit, offset }, meta }/api/v1/vehicles/{id} Full record for a single vehicle by slug.
{ data: { vehicle }, meta }/api/v1/pricing Auction-price aggregate + indicative landed cost for the destination market. `demo:true` when no live aggregate is available yet.
vehicle_id string required — Catalog slug. destination_country iso-2 required — Two-letter market code. { data: { vehicle_id, destination_country, auction_price_jpy{min,mid,max}, landed_cost_usd, last_updated, demo }, meta }/api/v1/rates Frankfurter-backed exchange rate with a 1-hour cache.
from iso-4217 required — USD, EUR, GBP, JPY, AUD, NZD, CAD, AED, KES. to iso-4217 required — Same set as `from`. { data: { from, to, rate, updated_at }, meta }/api/v1/container/optimize Pack items into a 40ft High-Cube; returns fill %, void cube, and suggested fillers.
items array required — Each item: { type, qty }. Types from kei-container-dims. { data: { total_units, volume_used_m3, volume_remaining_m3, fill_pct, void_suggestions[], estimated_freight_usd }, meta }/api/v1/hts/classify Deterministic HTS classification for common vehicle classes. Free-form line items go through /api/classify-hts.
vehicle_type string required — sedan, kei truck, parts, etc. fuel string required — electric, phev, petrol, diesel. engine_cc int — Used for combustion-engine routing. { data: { hts_code, description, common_duty_pct_us, common_duty_pct_uk, common_duty_pct_au }, meta }/api/v1/duties Indicative duty + VAT percentages for an HTS prefix in the chosen destination market.
hts_code string required — Full or prefix. destination_country iso-2 required — Two-letter code. { data: { hts_code, destination_country, duty_pct, vat_pct, additional_notes }, meta }/api/v1/vessels Returns the latest container event + vessel position. Pass either parameter; if no record is found, returns `data:null` with a message.
container_number string — Container or booking reference. bol_number string — Bill of lading number. { data: { vessel_name, imo, lat, lng, destination_port, eta, status }, meta }/api/v1/soh/estimate AI-assisted battery state-of-health estimate. Returns a percentage, confidence band, and recommended actions.
make string required model string required year int required mileage_km int required auction_grade string — Optional auction sheet grade. { data: { soh_pct, confidence, degradation_notes, recommended_actions[] }, meta }
Register an HTTPS endpoint via POST /api/v1/webhooks and we will post signed JSON to it when subscribed events fire. Each request carries X-WATTSHIP-Signature: an HMAC-SHA-256 hex digest of the raw body, signed with the secret returned at registration.
price_alert Fires when a watched make/model crosses a configured price threshold.
vessel_status Fires when a tracked vessel/container updates its status or ETA.
fx_threshold Fires when a watched currency pair moves through a configured rate band.
CC Enterprise
Programmatic API access is included in the CC Enterprise tier ($799 / month). Lower tiers cover the web app, marketplace, and dashboards.
View Pricing →