Completed Update Delivery

Completed delivery retains finished updates so an authorized service can recover them in order across reconnects. It has one logical consumer per lease. It is separate from Session Events: those event frames and their cursors are not delivery updates, receipts, or acknowledgements.

Authentication and ownership

Use the OAuth2 service access token with the required westiq/search scope. Delivery also requires explicit permission for the exact calling service identity. An ordinary API credential does not grant that permission. Tenant and client ownership come from the token’s established server-side mapping. Never supply tenant or client authority in the body, query, or headers.

The seven scoped routes use the server-minted passenger session’s canonical, lowercase, hyphenated, non-nil UUID in {id}. It is a locator, not a credential. Do not substitute X-Session-Id, seatId, memberSlot, or a query parameter. Delivery rejects X-Airline-Id, X-Tenant-Id, X-Client-Id, and X-Session-Id. Receipts likewise grant no authentication or ownership authority.

The authorized service must validate the browser session cookie before opening a lease and attest its expiry in cookieExpiresAtMs. This is a trust boundary: the platform cannot detect an authorized service deliberately re-attesting an old session under a new lease generation. Keep browser-cookie validation and freshness checks in that service; a new generation is not proof of a fresh browser session.

Operations and shapes

All success responses include schemaVersion: "1" and correlationId. The Completed delivery group in the API Reference defines the complete generated request and response shapes, including the eight update families. Objects are closed recursively: unknown fields are refused.

Open and append return 201 for a new commit, 200 for exact replay. Other successful operations return 200. Slot/cell discovery is advisory, not a reservation.

• epoch contains slot and generation. Slot is an integer from 0 through 29; receipt cell is an integer from 0 through 7.
• Generations, sequences, cursors and frontiers are canonical decimal strings, from "0" through "18446744073709551615", with no leading zeros. Do not convert them to a floating-point number.
• openId, updateId, readId and receipt token are lowercase hyphenated UUIDs. The nil UUID is valid for these fields, unlike the session locator.
• Timestamps are nonnegative integer Unix milliseconds, no larger than 9007199254740991.
• Each event contains sequence, updateId, payloadSha256, and update. A receipt contains cell, generation, token, from, through, and expiresAtMs. Ack sends only its proof fields: cell, generation, and token.

GET requests have no body or query parameters. POST requests use application/json, optionally with UTF-8 charset, with no content encoding. Duplicate properties, malformed UTF-8, unknown fields and excessive nesting refuse.

Commit, read, apply, acknowledge

1. Find an available slot, then open it with a stable openId and the returned generation. Preserve that entire request when retrying.
2. Complete and freeze an update before append. Preserve its updateId and body across retries. Notify the consumer only after append reports durable success. Preparing a payload or allocating an ID is not a commit.
3. Obtain an available receipt cell. Read after the consumer’s applied cursor, with a stable readId, cell and expected cell generation. Preserve the full read request when retrying.
4. Apply the returned contiguous range. nextCursor is the last returned sequence, not committedThrough. Only then acknowledge the applied range with its receipt. Receipt proof records delivery, not whether the consumer applied it.
5. Close when finished. Closing prevents new appends and receipts; it does not promise immediate capacity release or slot reuse.

Read returns at most 100 contiguous updates and considers at most one additional candidate. Response size can reduce the page further. A page result carries events and a receipt. An empty result echoes the supplied cursor. A known fully acknowledged retry returns already_applied, no events or receipt, and the original supplied cursor. Neither result advances local application state by itself.

An exact live read retry preserves the original range, token and expiry; it does not renew the receipt. Closed or lease-expired reads refuse, including replay. Ack returns advanced or already_applied; an already applied acknowledgement can remain a no-op while its owned generation is still addressable. A receipt for a different owner, generation or range does not authorize an acknowledgement.

A gap is a refusal, not permission to skip updates or invent a new cursor. A timeout or client disconnect is not proof of rollback. An ambiguous mutation may already have committed: resolve or repeat the same identity and request, never generate a replacement ID or automatically restart inference. The request has one shared two-second operation budget; this is not a network-latency guarantee.

Time and capacity limits

Capacity exhaustion refuses visibly; updates are not overwritten or silently truncated. Ack does not immediately delete events or release capacity. Logical expiry and close likewise do not imply immediate physical deletion. Reuse requires confirmed reclamation; clients must not assume that a timer automatically frees a slot.

Request-rate and zero-queue concurrency gates apply before body processing. Their process limits are not a promise of a global quota across service instances.

Byte and payload limits

Declared content length cannot replace the actual byte count. Field bounds count decoded UTF-8 bytes, not characters: generally 16 KiB prose, 32 KiB reasoning narrative, 128-byte identifiers and 2 KiB URI/path fields. The API Reference gives each field’s bound; array, nesting and total-envelope bounds apply together.

The eight update families are score-update, content-rerank, persona-update, context-update, destination-update, shopping-update, terminal-event, and error. Outer enrichmentCycle and timestamp must match the corresponding data values. Required, optional and nullable fields are distinct. Numeric ranges are validated without coercion or clamping. Shopping forYouRow admits at most 12 products and at most two per category.

Every declared string is protected. If protection would alter an identifier or link, the update refuses rather than breaking its references. Unknown extension objects and raw exceptions are not accepted. Do not recursively append delivery errors into a lease that is already exhausted or refusing writes.

Refusals and retry

Delivery operation errors use schemaVersion, code, a generic message, correlationId, and explicit ruleId: null when no rule applies. This is a delivery-specific exception to the null omission described for other endpoints in Errors & Limits. Foreign and missing ownership both yield a generic not-found response; no error discloses a foreign owner or internal state.

Use a finite Retry-After hint when supplied. Preserve the same request identity after ambiguity. Integrity refusals retain conservative capacity and require investigation; do not fabricate replacement history.

Empty routing responses

These responses have no error envelope or body and occur before authentication or body processing:

• An unsupported method on an exact known delivery path returns 405 with Allow naming the accepted method. There is no implicit HEAD operation.
• Unknown delivery paths, empty session segments, repeated or encoded separators, and trailing or extra delivery path segments return 404. They are never normalized into a valid operation.

Query parameters cannot select an operation or supply ownership. Unrelated API paths retain their existing routing behavior.