POST `/events`

Send one user turn or explicit action event to an existing session.

When to use:

• Natural-language user messages (text)
• Explicit action calls (kind + payload)

Request fields:

Field	Type	Required	Description
sessionId	string	Yes	Existing session ID
actor.actorId	string	No	Optional owner check; must match session owner
text	string	No*	Natural-language user message
kind	string	No*	Explicit action/event kind
payload	object	No	Structured payload for explicit actions
idempotencyKey	string	Conditional	Required for write kinds

* Send at least one of text or kind.

Write kinds that require idempotencyKey:

• command_book_by_option_id
• action_book_option
• action_confirm_price_change
• action_confirm_payment_card
• action_cancel_booking

Natural-language example:

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_1771456953407_g7p6233d",
    "actor": { "actorId": "partner_user_001" },
    "text": "Seattle Mar 20-23 1 room refundable",
    "idempotencyKey": "demo:sess_1771456953407_g7p6233d:search:001"
  }'

Explicit action example:

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_1771456953407_g7p6233d",
    "kind": "action_book_option",
    "payload": {
      "optionId": "1375108c-d021-4e45-a54a-e11ef553af07"
    },
    "idempotencyKey": "demo:sess_1771456953407_g7p6233d:book:001"
  }'

Example success (200):

{
  "data": {
    "sessionId": "sess_1771456953407_g7p6233d",
    "event": {
      "id": "evt_1771456966998",
      "kind": "search_query"
    },
    "result": {
      "traceId": "demo-tenant:partner_api:partner-chat:sess_1771456953407_g7p6233d:evt_1771456966998",
      "status": "shortlist",
      "message": {
        "text": "I found options matching your request in Seattle."
      },
      "artifacts": {
        "shortlist": [
          {
            "optionId": "3d49d4cb-22b1-4963-9280-508fb1190f5c",
            "name": "Inn at the Market",
            "pricePerNight": 276.66,
            "totalPrice": 980.67,
            "currency": "USD",
            "refundable": true,
            "rating": 4.8
          }
        ]
      }
    }
  }
}

Common errors:

• 400: sessionId is required
• 400: Invalid JSON payload
• 400: idempotencyKey is required for kind=<write_kind>
• 404: session_not_found
• 409: actor.actorId does not match the session owner (...)
• 401, 403, 429: auth/quota