# Brek AI Skill

> Integrates with the Brek Partner Core Chat API to create and continue hotel-search and booking assistant sessions, send user events, enforce anti-abuse call controls, and handle payment setup and confirmation without collecting raw card data.

- Skill: `johnalbertini14-glitch/brek-ai-skill` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds add johnalbertini14-glitch/brek-ai-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/johnalbertini14-glitch/brek-ai-skill/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs, AI & ML, Agent Building, REST & GraphQL APIs
- Tags: Api Integration, Brek, Core Chat Api, Hotel Booking, Idempotency, Payment
- Author: johnalbertini14-glitch (https://skillmd.com/u/johnalbertini14-glitch)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/johnalbertini14-glitch/brek-ai-skill

---


# 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`