Connect contract card

Read this card every session. Do not invent fields from memory. Machine copy: AGENTS.md · index: llms.txt.

Auth and hosts

Header: Authorization: ApiKey sk_test_* or sk_prod_*. There are no hotels:search / hotels:book scopes.
Test: https://test-api.bundleport.com with sk_test_* only.
Production: https://api.bundleport.com with sk_prod_* only.
Do not mix keys and hosts.

From	Field	Into
Search `options[]`	`id`	Quote `criteria.optionRefId`
Quote `optionQuote`	`optionRefId`	Book `input.optionRefId`
Book `booking.reference`	`bookingID`	Detail / cancel `bookingID`
Cancel	`cancelReference`	Persist; confirm status via detail

There is no bookingReference. Do not pass search id to book after a successful quote.

Connect Hotels transactional failures: HTTP 200 + errors[] with ERR_CODE_* / ERR_TYPE_*. Always inspect errors when response.ok.
Gateway: HTTP 401 / 403 / 429 / 5xx. Body is not aggregator errors[].
Search / SSE saturated: HTTP 503 { "error": "aggregator saturated", "code": "RESOURCE_EXHAUSTED" } on /availability and /availability/_stream only. Quote/book/cancel do not use this admission gate.
Book JSON shape: HTTP 400 { "code": "invalid_argument", "message" } (non-array rooms/remarks, or clientReference longer than 20 characters).
Content catalog: HTTP 400 / 404 / 500 + errors[]. Hotels booking has no HTTP 404.
There is no PRICE_CHANGED, NO_AVAILABILITY, CONFIRMED, or error_category on Hotels JSON.
Follow additionalData.recommended_action when present. Hints match top-level description only.

Quote optionQuote.status: STATUS_TYPE_OK or STATUS_TYPE_RQ only.
Book/detail/list booking.status: BOOK_STATUS_TYPE_OK, BOOK_STATUS_TYPE_KO, BOOK_STATUS_TYPE_ON_REQUEST, BOOK_STATUS_TYPE_CANCELLED, BOOK_STATUS_TYPE_UNKNOWN, BOOK_STATUS_TYPE_PENDING_COMMIT. There is no BOOK_STATUS_TYPE_RQ (RQ is quote-only).
Never invent PENDING or CONFIRMED.

settings.timeout is milliseconds.
Search default 10s (max 60s). Book floor 90s (values below 90000 ms are raised). Cancel floor 60s (values below 60000 ms are raised). Quote floor 2s.
Your HTTP client must outlive settings.timeout.

Book response fields hotel, holder, stay (holder and rooms[].paxes are request only).
Official npm/pypi HTTP SDKs (@bundleport/connect-hotels-sdk, bundleport-connect-hotels).
Buyer booking webhooks. Poll bookingdetail for BOOK_STATUS_TYPE_ON_REQUEST.
GraphQL as a buyer Hotels surface.

Codegen / IDE: this card + OpenAPI. Write fetch / httpx / net/http. Credentials stay in the buyer’s env.
Runtime booking: MCP Streamable HTTP (availability → quote → book → bookingDetail → cancel) at https://api.connect.bundleport.com/mcp. Same identifiers as REST. Not a substitute for OpenAPI.