Core Chat API Documentation

1. Contact leo@pageonelab.com.
2. Brek will issue your partner API key (and sandbox base URL).
3. Start testing with Postman or your own HTTP client.

Send one of these headers on every request (POST /sessions, POST /events, GET /sessions/{sessionId}):

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

Example:

curl "$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":"partner_user_001"}}'

POST /events uses the same auth header:

curl "$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":"sess_xxx","text":"find me a refundable vegas hotel"}'

/api/partner/v1/core-chat

• x-request-id: request trace ID
• x-ratelimit-limit
• x-ratelimit-remaining
• x-partner-id

The sequence below was captured from a real sandbox run on February 18, 2026.

Step 0: Create session

Variables for this step (field | definition | required):

• actor.actorId | Stable end-user ID in your partner system. | Yes
• actor.timezoneOffsetMinutes | User timezone offset in minutes. | No
• channel.workspaceId | Optional partner workspace/group identifier. | No
• conversation.channelId | Optional conversation key in your client app. | No

Input (POST /sessions):

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

Output (201):

{
  "data": {
    "sessionId": "sess_1771456953407_g7p6233d",
    "tenantId": "demo-tenant",
    "channel": {
      "type": "partner_api",
      "workspaceId": "partner-demo"
    },
    "conversation": {
      "id": "partner-chat:sess_1771456953407_g7p6233d",
      "channelId": "partner-chat",
      "threadTs": "sess_1771456953407_g7p6233d"
    },
    "actor": {
      "actorId": "partner_golden_user_done",
      "timezoneOffsetMinutes": -420
    }
  }
}

Step 1: Search request

Variables for this step (field | definition | required):

• sessionId | Session ID returned in Step 0. | Yes
• text | Natural-language search request from the user. | Yes
• idempotencyKey | Retry-safe dedupe key from partner side. | Recommended

Input (POST /events):

{
  "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"
}

Output (status=shortlist):

{
  "data": {
    "result": {
      "status": "shortlist",
      "message": {
        "text": "I found options matching your request in Las Vegas. Matched core filters: refundable only. Sorted by lowest total price first."
      },
      "artifacts": {
        "shortlist": [
          {
            "optionId": "1375108c-d021-4e45-a54a-e11ef553af07",
            "name": "Branding Iron Motel",
            "pricePerNight": 98.11,
            "totalPrice": 110.26,
            "currency": "USD",
            "refundable": true,
            "rating": 2,
            "distanceTo": "2.7 miles from Las Vegas",
            "detailsUrl": "http://localhost:3000/book/hotel/69450b14fc4f2dc72399a9ba?..."
          }
        ]
      }
    }
  }
}

Step 2: User asks to book option 1

Variables for this step (field | definition | required):

• sessionId | Session ID returned in Step 0. | Yes
• text | User booking-intent message. | Yes

Input (POST /events):

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

Output (status=guest_name_required):

{
  "data": {
    "result": {
      "status": "guest_name_required",
      "message": {
        "text": "Before I book, I need the check-in guest name for room 1: first name + last name exactly as shown on an official ID."
      }
    }
  }
}

Step 3: User provides guest name

Variables for this step (field | definition | required):

• sessionId | Session ID returned in Step 0. | Yes
• text | Guest-name message (for example: "guest name is John Doe"). | Yes

Input (POST /events):

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

Output (status=payment_setup_required):

{
  "data": {
    "result": {
      "status": "payment_setup_required",
      "message": {
        "text": "No payment method is set up for this account. Please add a card before booking. Set up here: http://localhost:3000/portal/payment?token=psu_1771456992743_e2634ddd\nPlease reply \"Done\" once you finished set up."
      },
      "artifacts": {
        "payment": {
          "setupUrl": "http://localhost:3000/portal/payment?token=psu_1771456992743_e2634ddd"
        }
      }
    }
  }
}

Step 3.5: User finishes card setup in payment portal

This happens outside Partner Core Chat endpoints (in Brek payment stack), but shown here for end-to-end clarity.

Variables for this step (field | definition | required):

• portalToken | Payment setup token returned in artifacts.payment.setupUrl. | Yes
• paymentMethodId | Payment method token from payment provider. | Yes
• cardBrand | Card brand (for example visa). | Yes
• cardLast4 | Last 4 digits of card. | Yes
• expMonth | Card expiration month. | Yes
• expYear | Card expiration year. | Yes
• setAsDefault | Whether to set this card as default. | No

Input (POST /v1/hotel-ea/payment-methods/attach on Brek payment backend):

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

Output:

{
  "data": {
    "status": "ATTACHED",
    "paymentMethod": {
      "paymentMethodId": "pm_card_visa",
      "brand": "visa",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2030
    }
  },
  "message": "success"
}

Step 4: User returns to chat and says "Done"

Variables for this step (field | definition | required):

• sessionId | Session ID returned in Step 0. | Yes
• text | Completion message after card setup (for example: "Done"). | Yes

Input (POST /events):

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

Output (status=payment_confirmation_required):

{
  "data": {
    "result": {
      "status": "payment_confirmation_required",
      "message": {
        "text": "I found your updated card: VISA •••• 4242. Use this card to continue booking?"
      },
      "artifacts": {
        "payment": {
          "paymentMethodId": "pm_card_visa",
          "cardBrand": "visa",
          "cardLast4": "4242",
          "expMonth": 12,
          "expYear": 2030
        }
      }
    }
  }
}

Step 5: User confirms payment and booking

Variables for this step (field | definition | required):

• sessionId | Session ID returned in Step 0. | Yes
• text | Confirmation message (for example: "yes, use this card"). | Yes

Input (POST /events):

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

Output (status=booked + confirmationUrl):

{
  "data": {
    "result": {
      "status": "booked",
      "message": {
        "text": "Booked Branding Iron Motel."
      },
      "artifacts": {
        "booking": {
          "bookingId": "A1WDDC",
          "confirmationBookingId": "699649fae0ee4bb440ddccf7",
          "hotelName": "Branding Iron Motel",
          "totalPrice": 110.26,
          "currency": "USD",
          "confirmationUrl": "http://localhost:3000/my-bookings/699649fae0ee4bb440ddccf7",
          "cancelPolicy": "Refundable until 2026-05-15T01:00:00Z"
        }
      }
    }
  }
}

Scenario A: user says "Done" but card is not attached yet

Variables for this scenario (field | definition | required):

• sessionId | Existing session ID. | Yes
• text | Completion message (for example: "Done"). | Yes

Input (POST /events):

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

Output (status=payment_setup_required again):

{
  "data": {
    "result": {
      "status": "payment_setup_required",
      "message": {
        "text": "Sure, you can update your payment method here: http://localhost:3000/portal/payment?token=psu_1771457050204_3d35ca69\nAfter setup, reply \"done\" in this thread and I will verify the new card before booking."
      },
      "artifacts": {
        "payment": {
          "setupUrl": "http://localhost:3000/portal/payment?token=psu_1771457050204_3d35ca69"
        }
      }
    }
  }
}

Scenario B: user already has a saved card

Variables for this scenario (field | definition | required):

• sessionId | Existing session ID. | Yes
• text | Guest-name message after booking intent. | Yes

Input (POST /events, after guest name):

{
  "sessionId": "sess_1771457174011_gavkkfv5",
  "text": "guest name is Jane Doe"
}

Output (status=payment_confirmation_required, no setup URL):

{
  "data": {
    "result": {
      "status": "payment_confirmation_required",
      "message": {
        "text": "Are you ok to pay with VISA •••• 4242?"
      },
      "artifacts": {
        "payment": {
          "paymentMethodId": "pm_card_visa",
          "cardBrand": "visa",
          "cardLast4": "4242",
          "expMonth": 12,
          "expYear": 2030
        }
      }
    }
  }
}

Scenario C: user declines payment confirmation

Variables for this scenario (field | definition | required):

• sessionId | Existing session ID. | Yes
• text | Decline message (for example: "no"). | Yes

Input (POST /events):

{
  "sessionId": "sess_1771457174011_gavkkfv5",
  "text": "no"
}

Output:

{
  "data": {
    "result": {
      "status": "error",
      "message": {
        "text": "No problem. I will not charge this card or continue this booking."
      }
    }
  }
}

Missing API key (401):

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

Invalid API key (403):

{
  "success": false,
  "error": "Invalid partner API key.",
  "code": "invalid_partner_api_key",
  "details": null,
  "requestId": "c75e34ff-aa06-4393-ae7d-cf1d31c3af25"
}

Missing idempotency key for write action (400):

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

Unknown session (404):

{
  "success": false,
  "error": "session_not_found",
  "details": {
    "error": "session_not_found"
  },
  "requestId": "ca6fc510-87ef-434a-a945-ba19ed0e118f"
}

• Retry 429 and 5xx with exponential backoff.
• Reuse the same idempotencyKey when retrying write actions.
• Log x-request-id for every failed request.

• Keep partner API keys server-side only.
• Use HTTPS/TLS for all requests.
• Do not send raw PCI card data in chat payloads.