HighQube API

Your own systems (a website, TMS or CRM) can use the prices and quotes your team sees in HighQube. A key acts for the organization that owns it: rate searches use its carrier contracts, and quotes are its quotes.

Getting started

1. An admin of your organization opens Control Panel → API Keys in HighQube and creates a key with the permissions it needs. The key is shown once: keep it in a secret manager.
2. Send it on every request: Authorization: Bearer hq_test_…. Keys for this test environment start with hq_test_; a key from another environment is refused.
3. Make a first call, a rate search from Shanghai to Los Angeles:

curl -G "https://api-dev.highqube.ai/rate-search" \
  -H "Authorization: Bearer $HIGHQUBE_API_KEY" \
  --data-urlencode 'routes=[{"origin":"CNSHA","destination":"USLAX"}]'

Keys

Keys belong to the organization, not to a person, so integrations keep working when people leave. By default a key lasts 180 days (an admin can choose 30, 90, 180 or 365), and admins are reminded 7 and 1 days before it expires. Rolling a key issues its replacement and keeps the old one working for a grace period (24 hours by default), so systems can switch over. A revoked key stops on the next request.

Permissions

Each endpoint names the permission (scope) it needs; a key without it is refused with insufficient_scope.

Errors

Every error has the same shape. errors[].field names the input to fix, and on a key refusal errors[0].code is a stable code to branch on.

{
  "success": false,
  "message": "Request failed",
  "errors": [
    {
      "message": "The API key does not have the quotes:write scope this endpoint requires.",
      "code": "insufficient_scope",
      "required_scope": "quotes:write"
    }
  ]
}

Rate limits

By default 120 requests a minute per key and 600 per organization, sustained. After a quiet spell a key may briefly go above that, up to 2 times its rate (its burst allowance), so a short spike is served rather than refused.

Every response to a request made with a key says where the key stands:

Over the limit, the answer is 429 rate_limited with a Retry-After header. Wait that many seconds and send the request again: nothing is lost, it is only delayed. Slowing down when X-RateLimit-Remaining gets low avoids the 429 altogether.

Retrying safely

Reads (searches, lookups, listing quotes) can always be sent again. Creating a quote (POST /rate-search/export) can be too, if you send an Idempotency-Key header: a value you choose, new for each quote, such as a UUID or your own order number. If a request times out or you are unsure it went through, send it again with the same key. No second quote is filed; you get the first one's workbook, with Idempotent-Replayed: true. The same key with a different request is refused with 422 idempotency_key_reused.

Restricting a key to your addresses

An admin can limit a key to your systems' IP addresses or ranges on the API Keys page. A call from anywhere else is refused with 403 ip_not_allowed, so a leaked key is of no use elsewhere. A key with no list works from any address.