Purserhouse for AI agents

Purserhouse is for US small and mid-size importers of goods made in China, and the customs brokers who serve them. Send a CBP Form 7501 for the IEEPA refund window and printed duty, or a demurrage and detention invoice for a check, the real last free day and a dispute basis. A person or company gives it their own documents; it returns every red line (anything that stops clearance or shipping), then at most three other findings on cost, risk or speed, and one next step. Agents can do this on the customer’s behalf.

The API contract below is a summary. /openapi.yaml is authoritative. The full guide written for language models is at /llms-full.txt , and a short index is at /llms.txt .

Machine-readable entry points

The flow

1. Look at coverage (no key). Call GET /api/v1/coverage or the MCP tool lanebrief_coverage to see lanes, ports, territories, container types, sides, document kinds and limits.
2. Get a key by requesting access (no key). POST /api/v1/access-requests or lanebrief_request_access with email, name, company, side, lanes and a note. The reply is 202. A person at Purserhouse reviews the request; the key (lb_live_...) is issued after access is granted.
3. Grant consent (key). The customer agrees once that their documents may be processed. POST /api/v1/consent or lanebrief_grant_consent. Before that, submissions fail with 403 consent_required.
4. Submit documents (key). POST /api/v1/cases or lanebrief_submit_documents. You get 202 with a case_id, status: "processing", a poll_url and retry_after. Add wait_seconds (0 to 25) to hold the call until the case is answered: if it is ready in time you get 200 with the result inline. Add idempotency_key (or rely on the files’ hashes) so that a retry returns the same case with duplicate: true instead of opening a second one.
5. Poll the result (key). GET /api/v1/cases/{id} or lanebrief_get_result, no more often than every retry_after seconds, until status is answered or failed. Not needed when the submit already returned the result.
6. Optional: details. GET /api/v1/cases/{id}/details or lanebrief_get_details returns the detailed breakdown behind the findings.

GET /api/v1/account (or lanebrief_account) shows the plan, whether billing is enabled, the free cases per month, how many are used and how many remain.

MCP client configuration

Most MCP clients that support remote HTTP servers accept a block like this. Replace the key with your own.

{
  "mcpServers": {
    "lanebrief": {
      "type": "http",
      "url": "https://purserhouse.com/mcp",
      "headers": {
        "Authorization": "Bearer lb_live_..."
      }
    }
  }
}

Tools: lanebrief_market_snapshot (no key), lanebrief_coverage, lanebrief_request_access (no key needed), lanebrief_grant_consent, lanebrief_submit_documents (files as base64), lanebrief_get_result, lanebrief_get_details, lanebrief_account; the free public tools (no key) lanebrief_refund_check, lanebrief_last_free_day, lanebrief_tariff_stack, lanebrief_screen, lanebrief_hs_rulings, lanebrief_dd_letter, lanebrief_isf_check.

REST examples

Coverage, no key:

curl https://purserhouse.com/api/v1/coverage

Request access, no key:

curl -X POST https://purserhouse.com/api/v1/access-requests \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"A. Buyer","company":"Example Trading","side":"importer","lanes":["CN-PG"],"note":"Agent integration"}'

Grant consent, once per key:

curl -X POST https://purserhouse.com/api/v1/consent \
  -H "Authorization: Bearer lb_live_..."

Submit documents as multipart:

curl -X POST https://purserhouse.com/api/v1/cases \
  -H "Authorization: Bearer lb_live_..." \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "lang=en" \
  -F "dest_country=AE"

Or as JSON:

curl -X POST https://purserhouse.com/api/v1/cases \
  -H "Authorization: Bearer lb_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Quote attached, 1x40HC Shanghai to Jebel Ali","lang":"en","dest_country":"AE","files":[{"name":"invoice.pdf","mime":"application/pdf","data_base64":"JVBERi0x..."}]}'

Poll:

curl https://purserhouse.com/api/v1/cases/CASE_ID \
  -H "Authorization: Bearer lb_live_..."

Public market data (no key)

GET /api/market is a free, public JSON snapshot. It is described in /openapi.yaml (getMarket) and is also the MCP tool lanebrief_market_snapshot (no key, no arguments, same JSON). Responses are cached for 60 seconds, CORS is open, and requests are rate limited per IP (HTTP 429 with Retry-After).

curl https://purserhouse.com/api/market

It contains as_of, fx (exchange rates with date, change and source), lanes (a freight trend index per lane with value, unit, date and source), watch (which data sources were updated and when, never their numbers), attributions and note. A value appears only when its licence allows it. It never contains forwarder medians or customer data, and the trend index is a market trend, not a quote. Show the attributions when you reuse it. Sources and cadence: Data and sources .

Free public tools (no key)

Seven JSON endpoints, described in /openapi.yaml (publicRefundCheck, publicLastFreeDay, publicTariffStack, publicScreen, publicHSRulings, publicDDLetter, publicISFCheck) and available as MCP tools without a key. They store nothing and call no model (except hs with q, which asks one for codes only); they run the same rules and licence gate as a customer case. Limit: 30 requests per 10 minutes per IP (screen: 10), then HTTP 429 with Retry-After. Errors are {"error": "..."}. Every response has sources and test_mode.

curl -X POST https://purserhouse.com/api/public/refund-check -H 'Content-Type: application/json' \
  -d '{"entry_date":"2025-12-01","origin":"CN","lines":[{"hts":"9903.01.24","duty":"1250.00"}]}'
curl 'https://purserhouse.com/api/public/last-free-day?carrier=MAEU&port=USLAX&arrival=2026-11-20&container=40'

Relay the JSON as returned. A null field, not_checked or computed: false means not calculated; do not fill it in.

What an answer looks like

The numbers below are an invented illustration of the shape, not a real result.

{
  "case_id": 123,
  "status": "answered",
  "lang": "en",
  "findings": [
    {"code": "net_weight_mismatch", "axis": "risk", "severity": "blocker", "title": "Documents do not match", "detail": "Net weight differs between invoice and packing list.", "red_line": true, "evidence": {"invoice": "3400", "packing": "3120"}},
    {"code": "quote_above_median", "axis": "cost", "severity": "medium", "title": "Quote above the market median", "detail": "...", "saving_usd": 250}
  ],
  "next_step": "Ask the factory for a corrected packing list.",
  "answer_text": "..."
}

If a number cannot be calculated from licensed data, the answer says “not calculated”. It is never filled in with a guess.

Errors

Errors have the shape {"error":{"code","message","hint"}}.

Rules agents must follow

• Send only the documents of the person or company you act for. Never send other people’s files.
• Never invent or round numbers in the answer. Quote the findings as given.
• Do not submit again while a case is processing. Poll instead.
• The result is guidance, not legal, customs or financial advice.
• Customer files are deleted after 7 days and are never used to train models.

Related

How Purserhouse differs from marketplaces, benchmarks and duty calculators: Purserhouse compared . The human version of the same service starts on the home page .

Updated: 2026-10-02