Brek AI Partner Core Chat

Execute Brek through /api/partner/v1/core-chat.

Use this execution order: 1. Create one session per end user (POST /sessions) with a stable actor.actorId. 2. Reuse that session for all follow-up messages (POST /events). 3. Read the latest state when needed (GET /sessions/{sessionId}).

Do not share one session across different users.

Required runtime inputs

Require these inputs before calling Brek: - BREK_BASE_URL - BREK_PARTNER_API_KEY - actorId (stable partner-side end-user ID) - workspaceId or tenant context if your product uses workspaces - partnerId (stable partner tenant ID for idempotency and billing grouping) - clientActionId for each write-like event kind

If one required input is missing, stop and request it.

If BREK_PARTNER_API_KEY is missing: - stop outbound calls - ask the user to get the key from their internal owner or approved support channel - never request secrets through unapproved channels

Call safety guardrails

Apply these guardrails before every upstream call: 1. Enforce local budget limits from references/call-control.md. 2. Attach a deterministic idempotencyKey for all write-like event kinds. 3. Respect 429 with retry-after and exponential backoff. 4. Open a circuit breaker after repeated 5xx or timeout failures. 5. Log x-request-id, x-partner-id, x-ratelimit-limit, and x-ratelimit-remaining.

Never retry booking or payment-confirm actions without the same idempotencyKey.

Event-kind rules

When kind is one of: - command_book_by_option_id - action_book_option - action_confirm_price_change - action_confirm_payment_card - action_cancel_booking

Always include idempotencyKey.

Generate idempotencyKey as: - <partnerId>:<sessionId>:<kind>:<clientActionId>

If partnerId is unavailable in your runtime, use stable tenant context (for example workspaceId) and keep the key format deterministic.

Payment handling

Handle payment in two layers: 1. End-user card setup and confirmation in secure portal flow. 2. Agent-to-agent usage billing and settlement.

Follow references/payment-and-billing.md for both layers.

Hard rules: - Never request or store raw card number, CVV, or full PAN in chat. - Accept only tokenized paymentMethodId from provider-hosted fields. - Require explicit user confirmation before action_confirm_payment_card and booking actions.

Response mapping

Map Brek response as: - data.result.status -> state machine key for UI and orchestration - data.result.message.text -> user-visible assistant text - data.result.artifacts -> structured payload (shortlist, payment setup URL, booking metadata)

Error handling

• 400: request validation failed. Fix payload.
• 401/403: API key issue. Stop calls. Tell user to rotate or provision key through their internal owner or approved support channel.
• 404: session not found or wrong tenant.
• 409: actor/session mismatch. Recreate correct session.
• 429: throttle locally and retry by retry-after.
• 5xx: retry with backoff, then open breaker.

References

Read only what you need: - API payload templates: references/api-templates.md - Call-control and anti-abuse policy: references/call-control.md - Payment and billing orchestration: references/payment-and-billing.md