Core Chat API Documentation

Brek Partner Core Chat API lets you embed Brek's hotel search and booking assistant in your own product.

Onboarding:

1. Contact leo@pageonelab.com.
2. Brek issues your partner API key and sandbox base URL.
3. Run the quickstart below and then move to endpoint details.

Last updated: February 24, 2026.

Prerequisites:

• Partner API key
• Brek base URL
• curl and jq

Set env vars:

export BREK_BASE_URL="https://www.brek.ai"
export BREK_PARTNER_API_KEY="<your_partner_api_key>"
export ACTOR_ID="partner_user_001"

1. Create a session:

SESSION_ID=$(curl -sS "$BREK_BASE_URL/api/partner/v1/core-chat/sessions" \
  -H "x-partner-api-key: $BREK_PARTNER_API_KEY" \
  -H "content-type: application/json" \
  -d "{\"actor\":{\"actorId\":\"$ACTOR_ID\",\"timezoneOffsetMinutes\":-480},\"channel\":{\"workspaceId\":\"partner-workspace\"},\"conversation\":{\"channelId\":\"partner-chat\"}}" \
  | jq -r '.data.sessionId')

echo "SESSION_ID=$SESSION_ID"

2. Send a user turn:

curl -sS "$BREK_BASE_URL/api/partner/v1/core-chat/events" \
  -H "x-partner-api-key: $BREK_PARTNER_API_KEY" \
  -H "content-type: application/json" \
  -d "{\"sessionId\":\"$SESSION_ID\",\"text\":\"Seattle Mar 20-23 1 room refundable\",\"idempotencyKey\":\"demo:$SESSION_ID:search:001\"}" \
  | jq

3. Read latest session snapshot:

curl -sS "$BREK_BASE_URL/api/partner/v1/core-chat/sessions/$SESSION_ID" \
  -H "x-partner-api-key: $BREK_PARTNER_API_KEY" \
  | jq

const baseUrl = process.env.BREK_BASE_URL!;
const apiKey = process.env.BREK_PARTNER_API_KEY!;

async function call(path: string, init?: RequestInit) {
  const res = await fetch(`${baseUrl}${path}`, {
    ...init,
    headers: {
      'content-type': 'application/json',
      'x-partner-api-key': apiKey,
      ...(init?.headers ?? {})
    }
  });

  const body = await res.json();
  if (!res.ok) throw new Error(JSON.stringify(body));
  return body;
}

const session = await call('/api/partner/v1/core-chat/sessions', {
  method: 'POST',
  body: JSON.stringify({
    actor: { actorId: 'partner_user_001', timezoneOffsetMinutes: -480 },
    channel: { workspaceId: 'partner-workspace' },
    conversation: { channelId: 'partner-chat' }
  })
});

const sessionId = session.data.sessionId;

const event = await call('/api/partner/v1/core-chat/events', {
  method: 'POST',
  body: JSON.stringify({
    sessionId,
    text: 'Seattle Mar 20-23 1 room refundable',
    idempotencyKey: `demo:${sessionId}:search:001`
  })
});

console.log(event.data.result.status);

import os
import requests

base_url = os.environ["BREK_BASE_URL"]
api_key = os.environ["BREK_PARTNER_API_KEY"]
headers = {
    "x-partner-api-key": api_key,
    "content-type": "application/json",
}

session_res = requests.post(
    f"{base_url}/api/partner/v1/core-chat/sessions",
    headers=headers,
    json={
        "actor": {"actorId": "partner_user_001", "timezoneOffsetMinutes": -480},
        "channel": {"workspaceId": "partner-workspace"},
        "conversation": {"channelId": "partner-chat"},
    },
    timeout=20,
)
session_res.raise_for_status()
session_id = session_res.json()["data"]["sessionId"]

event_res = requests.post(
    f"{base_url}/api/partner/v1/core-chat/events",
    headers=headers,
    json={
        "sessionId": session_id,
        "text": "Seattle Mar 20-23 1 room refundable",
        "idempotencyKey": f"demo:{session_id}:search:001",
    },
    timeout=20,
)
event_res.raise_for_status()
print(event_res.json()["data"]["result"]["status"])

For agent/tool integrations, use these directly:

• OpenAPI: https://www.brek.ai/openapi/partner-core-chat-v1.yaml
• LLM index: https://www.brek.ai/llms.txt
• Human docs page: https://www.brek.ai/docs/partner-core-chat

If you self-host, use the same paths on your own domain:

• /openapi/partner-core-chat-v1.yaml
• /llms.txt

Base path:

• /api/partner/v1/core-chat

Standard request headers:

• content-type: application/json
• one partner auth header (see Authentication section)

Common response headers (successful authenticated calls):

• x-request-id: request trace ID
• x-ratelimit-limit: minute quota for this key
• x-ratelimit-remaining: remaining requests in current window
• x-partner-id: resolved partner ID

Note:

• For early auth failures (401, 403), x-request-id is guaranteed; other headers may be absent.

Success envelope:

{
  "data": {
    "...": "endpoint-specific payload"
  }
}

Gateway error envelope:

{
  "success": false,
  "error": "human-readable message",
  "code": "machine_readable_code",
  "details": null,
  "requestId": "8f6f7d9d-74d5-4f37-8ef8-9c77d4f4ec2b"
}

Validation/proxy error envelope:

{
  "success": false,
  "error": "human-readable message",
  "requestId": "2a5ea99c-9884-448f-a442-35a883b64b31"
}

Send one of these headers on every request:

• x-partner-api-key: <partner_api_key> (recommended)
• Authorization: Bearer <partner_api_key>
• api-key: <partner_api_key>

Auth/quota behavior:

• Missing key -> 401, code=missing_partner_api_key
• Invalid key -> 403, code=invalid_partner_api_key
• Rate limited -> 429, code=rate_limited

Best practice:

• Keep keys server-side only
• Never expose partner keys in browser/mobile clients

Core objects:

• actor.actorId: stable partner-side end-user ID
• sessionId: Brek session key returned by POST /sessions
• data.result.status: state machine output for UI/agent branching
• data.result.artifacts: structured payload for your UI logic

Rules:

• Persist sessionId by actorId
• Never reuse one sessionId across different users
• If you send actor.actorId in POST /events, it must match the session owner

Always branch on data.result.status.

Retry policy:

• Retry only 429 and 5xx
• Use exponential backoff + jitter
• Keep the same idempotencyKey for retrying the same write action

Idempotency key format recommendation:

• <partner>:<sessionId>:<action>:<sequence>
• Example: demo:sess_1771456953407_g7p6233d:book:001

This sequence was captured from sandbox on February 18, 2026.

Step 0 (POST /sessions): create session

{
  "actor": {
    "actorId": "partner_golden_user_done",
    "timezoneOffsetMinutes": -420
  },
  "channel": {
    "workspaceId": "partner-demo"
  },
  "conversation": {
    "channelId": "partner-chat"
  }
}

Step 1 (POST /events): user search

{
  "sessionId": "sess_1771456953407_g7p6233d",
  "text": "find me a las vegas hotel from 5/15 to 5/16 that is cheap and refundable",
  "idempotencyKey": "demo:sess_1771456953407_g7p6233d:search:001"
}

Key output:

• result.status=shortlist
• artifacts.shortlist[] available

Step 2 (POST /events): user asks to book option

{
  "sessionId": "sess_1771456953407_g7p6233d",
  "text": "can you help me book option 1"
}

Key output:

• result.status=guest_name_required

Step 3 (POST /events): user shares guest name

{
  "sessionId": "sess_1771456953407_g7p6233d",
  "text": "guest name is John Doe"
}

Key output:

• result.status=payment_setup_required
• artifacts.payment.setupUrl available

Step 4 (outside partner core chat): user attaches card in payment portal

{
  "portalToken": "psu_1771456992743_e2634ddd",
  "paymentMethodId": "pm_card_visa",
  "cardBrand": "visa",
  "cardLast4": "4242",
  "expMonth": 12,
  "expYear": 2030,
  "setAsDefault": true
}

Step 5 (POST /events): user returns and says "Done"

{
  "sessionId": "sess_1771456953407_g7p6233d",
  "text": "Done"
}

Key output:

• result.status=payment_confirmation_required
• artifacts.payment available

Step 6 (POST /events): user confirms payment

{
  "sessionId": "sess_1771456953407_g7p6233d",
  "text": "yes, use this card"
}

Key output:

• result.status=booked
• artifacts.booking.confirmationUrl available

User says "Done" before card attach:

• Input: POST /events with text="Done"
• Output: result.status=payment_setup_required and a new setup URL

User already has saved card:

• Input: guest-name turn after booking intent
• Output: result.status=payment_confirmation_required directly

User declines payment confirmation:

• Input: POST /events with text="no"
• Output: result.status=error and booking is not continued

Example (401 missing key):

{
  "success": false,
  "error": "Missing partner API key.",
  "code": "missing_partner_api_key",
  "details": null,
  "requestId": "d813d7e3-ba0b-4a97-899d-0847590d7560"
}

Example (400 missing idempotencyKey):

{
  "success": false,
  "error": "idempotencyKey is required for kind=action_book_option",
  "requestId": "2a5ea99c-9884-448f-a442-35a883b64b31"
}

• Keep partner API keys server-side only
• Use HTTPS/TLS for all partner traffic
• Do not send raw PCI card data in chat payloads
• Log x-request-id and requestId for incident triage
• Ensure one session is always scoped to one actor

Before production launch:

• Persist sessionId by actorId
• Handle every known result.status
• Parse artifacts defensively (optional fields)
• Implement retry + idempotency policy
• Alert on repeated 401/403/429 and 5xx
• Keep keys in your secret manager
• Validate your integration against OpenAPI before release

Deterministic loop:

1. Ensure a session exists (POST /sessions once per actor lifecycle)
2. Send user turn (POST /events)
3. Branch only on data.result.status
4. Execute external steps (for example card setup) when required
5. Continue until terminal status (booked or error)

Agent guardrails:

• Never assume booking completion without status=booked
• Never call write kinds without idempotencyKey
• Never reuse one session across different actors
• Always propagate requestId and traceId into logs
• Prefer OpenAPI schema for request shaping and validation

For onboarding, production readiness review, or incident triage:

• leo@pageonelab.com