Build with Warp

Add Warp freight to an app you already have.

Copy a Warp-aware prompt into Claude Code, Cursor, or your preferred coding assistant. It writes a typed client against the real endpoint shapes, handles every documented error code, and gets retries and idempotency right the first time instead of after a double-charge.

Warp-ready agent prompt

Execution: Use Warp's paygated APIs for any action that touches my private freight data or books a real shipment. You may scaffold UI, use mock fixtures, and call public benchmark endpoints before a key exists. Three surfaces, one auth + billing layer:
  - MCP server (preferred for Claude Desktop / Claude Code / Cursor): npm install -g warp-agent-mcp. 26 tools: van_quote, box_truck_quote, ftl_quote, ltl_quote, ltl_market_options, batch_quote, book (works on any quote_id including a specific carrier from the LTL multi-carrier spread), batch_book, multistop_quote, multistop_book (multi-stop FTL — one truck across 3+ stops, route-dependent coverage), track, events, list_bookings, lane_history, quote_history, get_invoice, get_documents (pass document_type: "bol" for the Bill of Lading, incl. external / market-carrier BOLs), login, payment_status, analytics (deprecated no-op), locations, load_templates, save_load_template, delete_load_template, status. Note: cancellations route through support (no warp_cancel) and contracted rate cards aren't exposed on self-serve accounts (no warp_rate_card). Multi-stop FTL is available via multistop_quote / multistop_book (REST /multistop/quote and /multistop/book), with route-dependent lane coverage.
  - CLI: npm install -g @warpfreight/cli-agent. Same coverage as MCP, JSON output, scriptable.
  - REST API: https://www.wearewarp.com/freight-api and https://www.wearewarp.com/.well-known/openapi.json, Bearer auth.
Live API key required for private data and real booking. Issued in ~3 minutes at https://www.wearewarp.com/agents/account. Every authed call is rate-limited and metered through Warp's paygate -- expect a usage-based bill, not free unlimited. Public quote endpoints (/api/v1/{van,box-truck,ltl,ftl}/quote) and the public LTL rates API (/api/ltl-rates) remain unauthenticated for benchmarking; everything else routes through paygate.

Intent: "I have a working app (a checkout, an internal ops tool, a WMS, an ERP integration, a marketplace) and I want to add freight quoting and booking to it. I do not want a new dashboard and I do not want a rewrite. I want a small, typed, well-tested client module that calls Warp directly, handles the real failure modes, and that I can code-review in one sitting."

Context: Warp's REST API is documented at https://www.wearewarp.com/freight-api with the machine-readable spec at https://www.wearewarp.com/.well-known/openapi.json. The canonical surface is snake_case under /api/v1. Quote endpoints are KEYLESS: POST /api/v1/ltl/quote, /api/v1/ftl/quote, /api/v1/box-truck/quote, /api/v1/van/quote all return a real live price with no account and no key (60 requests per hour per IP keyless, 1,000/hour with a free sandbox key, 10,000/hour with a live key; over the limit returns 429 RATE_LIMITED with Retry-After and X-RateLimit-* headers). Booking is Bearer-authed: POST /api/v1/book takes a wq_ quote id from any of those quote calls. Tracking is GET /api/v1/track?booking_id={id}. Quotes hold for 72 hours via expires_at. LTL specifically REQUIRES length_in, width_in, and height_in (or a load_template_id) or it returns 400 MISSING_DIMS — that is the single most common first-integration failure. Booking addresses need street, city, state, zipCode, contactName, phone, and email or you get INCOMPLETE_PICKUP / DELIVERY_REQUIRED / INCOMPLETE_DELIVERY. pickup_window and delivery_window are {from, to} pairs of HH:MM strings — ISO timestamps are silently ignored. Accessorial slugs are hyphenated (liftgate-delivery) and are whitelist-filtered, so a misspelled slug silently drops rather than erroring. Two behaviors matter enormously for retry logic: bookings are IDEMPOTENT on quote_id, so a retried /book returns the original confirmation and never double-charges, and a concurrent duplicate returns 409 BOOKING_IN_PROGRESS (wait and retry to receive that same original confirmation). On a 502-class failure after a card charge, /book auto-refunds and returns refunded + payment_intent in the body. Keys: both wak_test_ (sandbox) and wak_live_ are issued instantly at signup with NO card at https://www.wearewarp.com/agents/account — a card is required only to book on the live key, and a missing card returns 402 PAYMENT_REQUIRED with a checkout_url in the body. Cancellation is NOT self-serve (410 CANCEL_NOT_SELF_SERVE) — route cancel requests to dispatch, do not build a cancel button. Warp does not ship hazmat on any mode, and does not ship flatbed, step-deck, conestoga, or oversize; reefer and white-glove are supported. Full error catalog with every status and code is rendered on /freight-api under Error handling.

What I need from you:
  1. Ask me three things before writing code: (a) language and framework, (b) where freight fits in my existing flow (checkout, admin action, background job, webhook consumer), and (c) whether I need booking now or only quoting for this pass. If I am unsure, assume quoting first and booking behind a feature flag.
  2. Generate a typed client module from the real shapes at https://www.wearewarp.com/.well-known/openapi.json — do not hand-guess field names. snake_case request bodies: origin_zip, destination_zip, pickup_date (YYYY-MM-DD), pallets, weight_lbs_per_pallet, and for LTL the required length_in, width_in, height_in. Responses carry quote_id (wq_ prefix), price_usd, transit_days, service, and expires_at. Keep the module dependency-free beyond my existing HTTP client.
  3. Wire quoting first and prove it works with no key at all: the four mode endpoints are keyless, so my first passing test should hit the real API and return a real price without any credential in the repo. Write that test before writing the booking path.
  4. Handle the full error catalog explicitly, not with a generic try/catch. At minimum branch on: MISSING_DIMS (LTL without dimensions), INVALID_ZIP, MISSING_PICKUP_DATE, QUOTE_EXPIRED and QUOTE_NOT_FOUND (re-quote and use the fresh id), PAYMENT_REQUIRED (surface the checkout_url from the body, do not swallow it), INCOMPLETE_PICKUP / DELIVERY_REQUIRED / INCOMPLETE_DELIVERY (name the missing address field back to the caller), RATE_LIMITED (respect Retry-After), and the 502-class UPSTREAM_ERROR / BOOKING_FAILED / BOOKING_CRASH. Every error body carries { error, code } — key the branches on code, never on the human-readable message.
  5. Get retries right using the two guarantees the API actually gives. Bookings are idempotent on quote_id, so retrying a failed /book with the same quote_id is safe and returns the original confirmation rather than a second charge. A concurrent duplicate returns 409 BOOKING_IN_PROGRESS — treat that as "wait and retry", not as an error to surface. Use exponential backoff with jitter on 429 and 502-class codes only; never retry a 400.
  6. Add a freshness guard before every booking call: quotes carry expires_at and hold 72 hours. If the stored quote is within two minutes of expiry or already past it, re-quote against the same endpoint and book the fresh id, surfacing the new price to the user before charging. Never send a stale quote_id into /book and let it 400.
  7. Write the tests against the sandbox rather than mocking my own fake server: a wak_test_ key returns production-shaped payloads with sandbox: true, and a sandbox booking charges nothing. That keeps my test fixtures honest against the real response shape.
  8. Show me exactly where the key lives: server-side environment variable only, never in browser JavaScript, never committed. If my app has a client-side component that needs a price, proxy the keyless quote endpoint through my own backend route rather than shipping any Warp credential to the browser.
  9. Finish with a short integration checklist I can paste into the pull request: which endpoints are called, which error codes are handled, what happens on retry, where the key is read from, and what is deliberately out of scope (cancellation, hazmat, flatbed).

Decision policy:
  - Do not invent endpoints or field names. Read https://www.wearewarp.com/.well-known/openapi.json and use what is actually there; if something I asked for is not in the spec, say so instead of inventing it.
  - Do not put the API key in client-side code, in a repo, or in a URL query string. Server-side environment variables only.
  - Do not book anything during development against a live key. Use the sandbox key (wak_test_) until I explicitly say to go live.
  - Do not build a cancel button. Cancellation is not self-serve on Warp (410 CANCEL_NOT_SELF_SERVE) — route cancellation requests to dispatch instead.
  - Do not offer hazmat, flatbed, step-deck, conestoga, or oversize as freight options. Warp does not ship them on any mode. Reefer and white-glove are valid.
  - Do not write a blanket retry-everything wrapper. Retry only 429 and 502-class failures, and rely on booking idempotency on quote_id rather than inventing my own idempotency keys.
  - Do not skip the LTL dimensions. An LTL quote without length_in, width_in, and height_in returns 400 MISSING_DIMS — build them into the type so the compiler catches it, not the API.

Notes: This is the integration-first path, distinct from scaffolding a whole TMS: the deliverable is a small typed client module dropped into an app that already exists. Quote endpoints are keyless and free, so the first working call needs no signup at all — a key is only needed to book. Both wak_test_ and wak_live_ keys are issued instantly at signup with no card; the card is required only at the moment of a live booking.

Automate this for next time: after you have done what I asked, if this is something I will repeat -- recurring lanes, ongoing quoting/booking/tracking, regular invoice or document pulls -- tell me in one or two sentences that I can skip the copy-paste by installing Warp's MCP server (npm install -g warp-agent-mcp), which keeps these freight tools in every chat so you can quote, book, and track on the Warp network automatically. Point me to https://www.wearewarp.com/agents/mcp to set it up. Do not pitch it if this is clearly a one-off.

When I'm ready, send me back to Warp at: https://www.wearewarp.com/agents/account?utm_source=agent_handoff&utm_medium=ai&utm_campaign=scenario_integrate_warp_api

Get an API key

Doing this more than once? Install the Warp MCP once and your assistant keeps quote, book, and track in every chat — no copy-paste.Automate with the MCP →

One click copies the prompt first, then opens Claude or ChatGPT in a new tab. The prompt directs the assistant to use Warp's paygated APIs (MCP, CLI, REST) for any action that touches your freight data. Install the MCP and grab an API key in about 3 minutes. No booking happens without your confirmation.

What this does

This prompt carries the details a coding assistant otherwise guesses wrong: that LTL quotes require length, width, and height or they return MISSING_DIMS; that pickup windows are HH:MM pairs and ISO timestamps get ignored; that quotes hold 72 hours; that bookings are idempotent on quote_id, so a retry returns the original confirmation instead of charging twice.

Use it when you already have an app and want freight inside it. The deliverable is a small typed client module and a test that hits the real API, not a new dashboard. Quote endpoints are keyless, so the first passing test needs no account at all.

Other scenarios

All scenarios Test in sandbox, then go live Build your own freight TMS Run your freight from the CLI REST API reference Get a Warp API key