> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Report site events straight from the browser (publishable key, no response body)

> The browser path for the same events as `POST /events`, for sites without a server of their own and for MarketBox’s own widget. Built for `navigator.sendBeacon` and `fetch(…, { keepalive: true })` on a page that may be closing, so nothing about it needs a header: the credential is the publishable key in `?key=pk_…`, the body may be `text/plain` as well as `application/json` (no CORS preflight), and the answer is 204 with no body. `@mb-core/insights-beacon` does all of this for you.

**The publishable key** is minted with the application and shown on the API Access screen beside the API key. It is public by design — it ships in your page — and can only do this: send events, from the exact origins listed on the application (`https://book.acme.com`, never `*`). The browser’s `Origin` header must be one of them; a missing or other origin is refused (403). Keep the API key on your server; it is never accepted here (401).

**Limits.** At most 50 events and 64 KB per beacon (413 past either, nothing read). About 50 beacons a second per key, with bursts of 100 (429 past that). Each event is validated on its own exactly as on `POST /events`, with the same rules: `occurredAt` within 24 hours ahead and 72 hours back, supplier ids of this project, a place as an H3 cell or `lat`/`lng` reduced on receipt. A rejected event is dropped silently (the 204 says nothing); send from your server with `POST /events` when you want the rejections back. Events are stored with `channel: "browser"`; a `searchId` is kept as sent.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/events/beacon
openapi: 3.0.0
info:
  title: MarketBox 2.0 Open API
  version: 1.0.0
  description: >-
    The MarketBox public API for building booking experiences. Core model:
    create an order, then draw its order items down into bookings. Single
    bookings reference an order item per service line; package bookings draw one
    PACKAGE item down across N sessions. To schedule a package, build a slate
    (POST /availability/package-slate) and book it by slateId (POST
    /orders/{orderId}/package-bookings). See the guides for end-to-end
    walkthroughs.
  contact:
    name: MarketBox support
servers:
  - url: https://apiv2.gomarketbox.com
    description: MarketBox Open API
security:
  - ApiKeyAuth: []
paths:
  /v1/projects/{projectId}/events/beacon:
    post:
      tags:
        - Events
      summary: >-
        Report site events straight from the browser (publishable key, no
        response body)
      description: >-
        The browser path for the same events as `POST /events`, for sites
        without a server of their own and for MarketBox’s own widget. Built for
        `navigator.sendBeacon` and `fetch(…, { keepalive: true })` on a page
        that may be closing, so nothing about it needs a header: the credential
        is the publishable key in `?key=pk_…`, the body may be `text/plain` as
        well as `application/json` (no CORS preflight), and the answer is 204
        with no body. `@mb-core/insights-beacon` does all of this for you.


        **The publishable key** is minted with the application and shown on the
        API Access screen beside the API key. It is public by design — it ships
        in your page — and can only do this: send events, from the exact origins
        listed on the application (`https://book.acme.com`, never `*`). The
        browser’s `Origin` header must be one of them; a missing or other origin
        is refused (403). Keep the API key on your server; it is never accepted
        here (401).


        **Limits.** At most 50 events and 64 KB per beacon (413 past either,
        nothing read). About 50 beacons a second per key, with bursts of 100
        (429 past that). Each event is validated on its own exactly as on `POST
        /events`, with the same rules: `occurredAt` within 24 hours ahead and 72
        hours back, supplier ids of this project, a place as an H3 cell or
        `lat`/`lng` reduced on receipt. A rejected event is dropped silently
        (the 204 says nothing); send from your server with `POST /events` when
        you want the rejections back. Events are stored with `channel:
        "browser"`; a `searchId` is kept as sent.
      parameters:
        - schema:
            type: string
            minLength: 1
            description: >-
              The project (tenant) that owns the resource. Every resource in
              this API is scoped to a project, and your API key is restricted to
              the projects it was issued for — a project outside that scope
              returns 403.
            example: prj_01kv60qgnef2kt3pvqgwmkbzfr
          required: true
          description: >-
            The project (tenant) that owns the resource. Every resource in this
            API is scoped to a project, and your API key is restricted to the
            projects it was issued for — a project outside that scope returns
            403.
          name: projectId
          in: path
        - schema:
            type: string
            description: >-
              The application’s publishable key, `pk_…`, from the dashboard’s
              API Access screen. It is public by design and may only send
              events, from the origins listed on the application. An API key is
              never accepted here (401).
            example: pk_01k7q3x9h4e8rb2d6m0z5a7c1n
          required: true
          description: >-
            The application’s publishable key, `pk_…`, from the dashboard’s API
            Access screen. It is public by design and may only send events, from
            the origins listed on the application. An API key is never accepted
            here (401).
          name: key
          in: query
      requestBody:
        description: The batch of events, as JSON. Sent as `text/plain` by a beacon.
        required: true
        content:
          text/plain:
            schema:
              $ref: '#/components/schemas/SiteEventsBeaconBatch'
          application/json:
            schema:
              $ref: '#/components/schemas/SiteEventsBeaconBatch'
      responses:
        '204':
          description: The beacon was read; accepted events are recorded. No body.
        '400':
          description: 'Not a batch: the body is not JSON or has no `events` array'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: >-
            No publishable key in `?key=`, or not a live one (an API key is
            never accepted here)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: >-
            The `Origin` is missing or not in the application’s allowlist, or
            the key belongs to another project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '413':
          description: Over 50 events or 64 KB; nothing was read
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too many beacons from this key; retry after a second
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '503':
          description: >-
            MarketBox could not check the key or the suppliers; nothing was
            recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security: []
components:
  schemas:
    SiteEventsBeaconBatch:
      type: object
      properties:
        events:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/SiteEventOpportunity'
              - $ref: '#/components/schemas/SiteEventImpression'
              - $ref: '#/components/schemas/SiteEventClick'
              - $ref: '#/components/schemas/SiteEventProfileView'
              - $ref: '#/components/schemas/SiteEventCoverageMiss'
              - $ref: '#/components/schemas/SiteEventSearchRendered'
            discriminator:
              propertyName: type
              mapping:
                opportunity: '#/components/schemas/SiteEventOpportunity'
                impression: '#/components/schemas/SiteEventImpression'
                click: '#/components/schemas/SiteEventClick'
                profile_view: '#/components/schemas/SiteEventProfileView'
                coverage_miss: '#/components/schemas/SiteEventCoverageMiss'
                search.rendered: '#/components/schemas/SiteEventSearchRendered'
            description: >-
              One site event. `type` picks the shape; the fields every type
              shares are listed on each.
          minItems: 1
          maxItems: 50
          description: >-
            The events, at most 50 per beacon (and 64 KB in all). The same
            shapes as `POST /events`; each is validated on its own and a
            rejected one never fails the batch.
          example:
            - eventId: lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b
              type: search.rendered
              occurredAt: '2026-10-03T14:05:10.020Z'
              sessionKey: sess-example-01
              searchId: srch_01k7q3x9h4e8rb2d6m0z5a7c1n
              surface: widget
              suppliers:
                - supplierId: sup_01kv60qh3m7wznp8s0d2rk9abc
                  position: 0
      required:
        - events
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
          description: Stable machine-readable error code, e.g. NOT_FOUND.
        message:
          type: string
          description: Human-readable description of what went wrong.
        statusCode:
          type: integer
          description: The HTTP status code of this response.
        requestId:
          type: string
          description: >-
            The id of this request, also returned as the X-Request-Id header.
            Quote it in a support ticket.
      required:
        - code
        - message
        - statusCode
        - requestId
      example:
        code: NOT_FOUND
        message: Booking not found
        statusCode: 404
        requestId: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
    SiteEventOpportunity:
      type: object
      properties:
        type:
          type: string
          enum:
            - opportunity
          example: opportunity
          description: 'A list that includes suppliers was drawn: one event per list render.'
        eventId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            Your id for this event — a UUID (v4 or v7), unique within the
            project. The idempotency key: a retry re-sending the same id is
            accepted and counted once.
          example: lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b
        occurredAt:
          type: string
          format: date-time
          description: >-
            When it happened, as an ISO 8601 instant with an offset or `Z`
            (R-1). Rejected per event when more than 24 hours ahead of receipt,
            or older than 72 hours without the `events:import` capability (400
            days with it).
          example: '2026-10-03T14:05:10.020Z'
        sessionKey:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            An opaque per-session key you hash yourself, at most 64 characters.
            Never an email, IP or user id. Alternatively the `X-MB-Session-Key`
            header.
          example: sess-example-01
        searchId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            The `searchId` of the MarketBox search response the list came from,
            when it did (the `X-MB-Search-Id` header / body field of every
            search route).
          example: srch_01k7q3x9h4e8rb2d6m0z5a7c1n
        path:
          type: string
          maxLength: 300
          description: >-
            The page path, at most 300 characters. The query string is stripped
            on receipt.
          example: /en-ca/book/results
        serviceId:
          type: string
          minLength: 1
          maxLength: 128
          description: The service the list or search was for, when there was one.
          example: srv_01kv60qg12e82acr78edfnjhvv
        locale:
          type: string
          minLength: 2
          maxLength: 16
          description: The page locale, as a BCP 47 tag.
          example: en-CA
        h3:
          type: string
          pattern: ^88[0-9a-f]{13}$
          description: >-
            The place in the event as a resolution-8 H3 cell. Send this or
            `lat`/`lng`, not both.
          example: 882b8e4a0dfffff
        lat:
          type: number
          minimum: -90
          maximum: 90
          description: >-
            Latitude of the place in the event. Reduced to a resolution-8 H3
            cell on receipt; never stored.
          example: 43.6532
        lng:
          type: number
          minimum: -180
          maximum: 180
          description: >-
            Longitude of the place in the event. Reduced to a resolution-8 H3
            cell on receipt; never stored.
          example: -79.3832
        surface:
          type: string
          enum:
            - home
            - results
            - listing
            - site_search
            - profile
            - widget
            - assistant
            - other
          description: Where on the site the list was drawn.
          example: results
        suppliers:
          type: array
          items:
            type: object
            properties:
              supplierId:
                type: string
                minLength: 1
                maxLength: 128
                description: >-
                  The MarketBox supplier id. Must belong to this project, or the
                  event is rejected.
                example: sup_01kv60qh3m7wznp8s0d2rk9abc
              position:
                type: integer
                minimum: 0
                description: >-
                  0-based rank in the list as drawn (the same number a search
                  response returns).
                example: 0
            required:
              - supplierId
              - position
            additionalProperties: false
          maxItems: 100
          description: >-
            The suppliers actually put on the page, in the order drawn, at most
            100. Every id must belong to this project, or the whole event is
            rejected.
          example:
            - supplierId: sup_01kv60qh3m7wznp8s0d2rk9abc
              position: 0
            - supplierId: sup_01kv60qh3m7wznp8s0d2rk9def
              position: 1
      required:
        - type
        - eventId
        - occurredAt
        - surface
        - suppliers
      additionalProperties: false
    SiteEventImpression:
      type: object
      properties:
        type:
          type: string
          enum:
            - impression
          example: impression
          description: >-
            A supplier's card reached the screen (≥ 50 % in the viewport) for
            the first time in that list render.
        eventId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            Your id for this event — a UUID (v4 or v7), unique within the
            project. The idempotency key: a retry re-sending the same id is
            accepted and counted once.
          example: lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b
        occurredAt:
          type: string
          format: date-time
          description: >-
            When it happened, as an ISO 8601 instant with an offset or `Z`
            (R-1). Rejected per event when more than 24 hours ahead of receipt,
            or older than 72 hours without the `events:import` capability (400
            days with it).
          example: '2026-10-03T14:05:10.020Z'
        sessionKey:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            An opaque per-session key you hash yourself, at most 64 characters.
            Never an email, IP or user id. Alternatively the `X-MB-Session-Key`
            header.
          example: sess-example-01
        searchId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            The `searchId` of the MarketBox search response the list came from,
            when it did (the `X-MB-Search-Id` header / body field of every
            search route).
          example: srch_01k7q3x9h4e8rb2d6m0z5a7c1n
        path:
          type: string
          maxLength: 300
          description: >-
            The page path, at most 300 characters. The query string is stripped
            on receipt.
          example: /en-ca/book/results
        serviceId:
          type: string
          minLength: 1
          maxLength: 128
          description: The service the list or search was for, when there was one.
          example: srv_01kv60qg12e82acr78edfnjhvv
        locale:
          type: string
          minLength: 2
          maxLength: 16
          description: The page locale, as a BCP 47 tag.
          example: en-CA
        h3:
          type: string
          pattern: ^88[0-9a-f]{13}$
          description: >-
            The place in the event as a resolution-8 H3 cell. Send this or
            `lat`/`lng`, not both.
          example: 882b8e4a0dfffff
        lat:
          type: number
          minimum: -90
          maximum: 90
          description: >-
            Latitude of the place in the event. Reduced to a resolution-8 H3
            cell on receipt; never stored.
          example: 43.6532
        lng:
          type: number
          minimum: -180
          maximum: 180
          description: >-
            Longitude of the place in the event. Reduced to a resolution-8 H3
            cell on receipt; never stored.
          example: -79.3832
        listId:
          type: string
          minLength: 1
          maxLength: 128
          description: The `eventId` of the `opportunity` this card belongs to.
          example: lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b
        supplierId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            The MarketBox supplier id. Must belong to this project, or the event
            is rejected.
          example: sup_01kv60qh3m7wznp8s0d2rk9abc
        position:
          type: integer
          minimum: 0
          description: >-
            0-based rank in the list as drawn (the same number a search response
            returns).
          example: 0
      required:
        - type
        - eventId
        - occurredAt
        - listId
        - supplierId
        - position
      additionalProperties: false
    SiteEventClick:
      type: object
      properties:
        type:
          type: string
          enum:
            - click
          example: click
          description: The client opened a supplier's profile or card from a list.
        eventId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            Your id for this event — a UUID (v4 or v7), unique within the
            project. The idempotency key: a retry re-sending the same id is
            accepted and counted once.
          example: lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b
        occurredAt:
          type: string
          format: date-time
          description: >-
            When it happened, as an ISO 8601 instant with an offset or `Z`
            (R-1). Rejected per event when more than 24 hours ahead of receipt,
            or older than 72 hours without the `events:import` capability (400
            days with it).
          example: '2026-10-03T14:05:10.020Z'
        sessionKey:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            An opaque per-session key you hash yourself, at most 64 characters.
            Never an email, IP or user id. Alternatively the `X-MB-Session-Key`
            header.
          example: sess-example-01
        searchId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            The `searchId` of the MarketBox search response the list came from,
            when it did (the `X-MB-Search-Id` header / body field of every
            search route).
          example: srch_01k7q3x9h4e8rb2d6m0z5a7c1n
        path:
          type: string
          maxLength: 300
          description: >-
            The page path, at most 300 characters. The query string is stripped
            on receipt.
          example: /en-ca/book/results
        serviceId:
          type: string
          minLength: 1
          maxLength: 128
          description: The service the list or search was for, when there was one.
          example: srv_01kv60qg12e82acr78edfnjhvv
        locale:
          type: string
          minLength: 2
          maxLength: 16
          description: The page locale, as a BCP 47 tag.
          example: en-CA
        h3:
          type: string
          pattern: ^88[0-9a-f]{13}$
          description: >-
            The place in the event as a resolution-8 H3 cell. Send this or
            `lat`/`lng`, not both.
          example: 882b8e4a0dfffff
        lat:
          type: number
          minimum: -90
          maximum: 90
          description: >-
            Latitude of the place in the event. Reduced to a resolution-8 H3
            cell on receipt; never stored.
          example: 43.6532
        lng:
          type: number
          minimum: -180
          maximum: 180
          description: >-
            Longitude of the place in the event. Reduced to a resolution-8 H3
            cell on receipt; never stored.
          example: -79.3832
        supplierId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            The MarketBox supplier id. Must belong to this project, or the event
            is rejected.
          example: sup_01kv60qh3m7wznp8s0d2rk9abc
        impressionId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            The `eventId` of the `impression` that was clicked. Send this, or
            `listId` when you do not track impressions.
          example: imp_2b7e1d5c-9f4a-4b8e-a3c6-7d0e2f1a9b4c
        listId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            The `eventId` of the `opportunity` the card was in, when no
            `impressionId` is known.
          example: lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b
      required:
        - type
        - eventId
        - occurredAt
        - supplierId
      additionalProperties: false
    SiteEventProfileView:
      type: object
      properties:
        type:
          type: string
          enum:
            - profile_view
          example: profile_view
          description: A supplier's profile page loaded, from anywhere.
        eventId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            Your id for this event — a UUID (v4 or v7), unique within the
            project. The idempotency key: a retry re-sending the same id is
            accepted and counted once.
          example: lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b
        occurredAt:
          type: string
          format: date-time
          description: >-
            When it happened, as an ISO 8601 instant with an offset or `Z`
            (R-1). Rejected per event when more than 24 hours ahead of receipt,
            or older than 72 hours without the `events:import` capability (400
            days with it).
          example: '2026-10-03T14:05:10.020Z'
        sessionKey:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            An opaque per-session key you hash yourself, at most 64 characters.
            Never an email, IP or user id. Alternatively the `X-MB-Session-Key`
            header.
          example: sess-example-01
        searchId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            The `searchId` of the MarketBox search response the list came from,
            when it did (the `X-MB-Search-Id` header / body field of every
            search route).
          example: srch_01k7q3x9h4e8rb2d6m0z5a7c1n
        path:
          type: string
          maxLength: 300
          description: >-
            The page path, at most 300 characters. The query string is stripped
            on receipt.
          example: /en-ca/book/results
        serviceId:
          type: string
          minLength: 1
          maxLength: 128
          description: The service the list or search was for, when there was one.
          example: srv_01kv60qg12e82acr78edfnjhvv
        locale:
          type: string
          minLength: 2
          maxLength: 16
          description: The page locale, as a BCP 47 tag.
          example: en-CA
        h3:
          type: string
          pattern: ^88[0-9a-f]{13}$
          description: >-
            The place in the event as a resolution-8 H3 cell. Send this or
            `lat`/`lng`, not both.
          example: 882b8e4a0dfffff
        lat:
          type: number
          minimum: -90
          maximum: 90
          description: >-
            Latitude of the place in the event. Reduced to a resolution-8 H3
            cell on receipt; never stored.
          example: 43.6532
        lng:
          type: number
          minimum: -180
          maximum: 180
          description: >-
            Longitude of the place in the event. Reduced to a resolution-8 H3
            cell on receipt; never stored.
          example: -79.3832
        supplierId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            The MarketBox supplier id. Must belong to this project, or the event
            is rejected.
          example: sup_01kv60qh3m7wznp8s0d2rk9abc
        referrerClass:
          type: string
          enum:
            - internal
            - search
            - direct
            - social
            - ads
            - other_site
            - assistant
          description: >-
            How the visitor reached the profile page: from your own site, a
            search engine, a typed URL, a social network, an ad, another site,
            or an AI assistant.
          example: internal
      required:
        - type
        - eventId
        - occurredAt
        - supplierId
        - referrerClass
      additionalProperties: false
    SiteEventCoverageMiss:
      type: object
      properties:
        type:
          type: string
          enum:
            - coverage_miss
          example: coverage_miss
          description: >-
            A client entered an address and the site found nobody, without
            calling a MarketBox search.
        eventId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            Your id for this event — a UUID (v4 or v7), unique within the
            project. The idempotency key: a retry re-sending the same id is
            accepted and counted once.
          example: lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b
        occurredAt:
          type: string
          format: date-time
          description: >-
            When it happened, as an ISO 8601 instant with an offset or `Z`
            (R-1). Rejected per event when more than 24 hours ahead of receipt,
            or older than 72 hours without the `events:import` capability (400
            days with it).
          example: '2026-10-03T14:05:10.020Z'
        sessionKey:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            An opaque per-session key you hash yourself, at most 64 characters.
            Never an email, IP or user id. Alternatively the `X-MB-Session-Key`
            header.
          example: sess-example-01
        searchId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            The `searchId` of the MarketBox search response the list came from,
            when it did (the `X-MB-Search-Id` header / body field of every
            search route).
          example: srch_01k7q3x9h4e8rb2d6m0z5a7c1n
        path:
          type: string
          maxLength: 300
          description: >-
            The page path, at most 300 characters. The query string is stripped
            on receipt.
          example: /en-ca/book/results
        serviceId:
          type: string
          minLength: 1
          maxLength: 128
          description: The service the list or search was for, when there was one.
          example: srv_01kv60qg12e82acr78edfnjhvv
        locale:
          type: string
          minLength: 2
          maxLength: 16
          description: The page locale, as a BCP 47 tag.
          example: en-CA
        h3:
          type: string
          pattern: ^88[0-9a-f]{13}$
          description: >-
            The place in the event as a resolution-8 H3 cell. Send this or
            `lat`/`lng`, not both.
          example: 882b8e4a0dfffff
        lat:
          type: number
          minimum: -90
          maximum: 90
          description: >-
            Latitude of the place in the event. Reduced to a resolution-8 H3
            cell on receipt; never stored.
          example: 43.6532
        lng:
          type: number
          minimum: -180
          maximum: 180
          description: >-
            Longitude of the place in the event. Reduced to a resolution-8 H3
            cell on receipt; never stored.
          example: -79.3832
      required:
        - type
        - eventId
        - occurredAt
      additionalProperties: false
    SiteEventSearchRendered:
      type: object
      properties:
        type:
          type: string
          enum:
            - search.rendered
          example: search.rendered
          description: >-
            The results of a MarketBox search were drawn. This is what makes a
            search count: a search with no render counts for nothing. A later
            page drawn is another event with the same `searchId`.
        eventId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            Your id for this event — a UUID (v4 or v7), unique within the
            project. The idempotency key: a retry re-sending the same id is
            accepted and counted once.
          example: lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b
        occurredAt:
          type: string
          format: date-time
          description: >-
            When it happened, as an ISO 8601 instant with an offset or `Z`
            (R-1). Rejected per event when more than 24 hours ahead of receipt,
            or older than 72 hours without the `events:import` capability (400
            days with it).
          example: '2026-10-03T14:05:10.020Z'
        sessionKey:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            An opaque per-session key you hash yourself, at most 64 characters.
            Never an email, IP or user id. Alternatively the `X-MB-Session-Key`
            header.
          example: sess-example-01
        searchId:
          type: string
          minLength: 1
          maxLength: 128
          description: The `searchId` of the search response whose results were drawn.
          example: srch_01k7q3x9h4e8rb2d6m0z5a7c1n
        path:
          type: string
          maxLength: 300
          description: >-
            The page path, at most 300 characters. The query string is stripped
            on receipt.
          example: /en-ca/book/results
        serviceId:
          type: string
          minLength: 1
          maxLength: 128
          description: The service the list or search was for, when there was one.
          example: srv_01kv60qg12e82acr78edfnjhvv
        locale:
          type: string
          minLength: 2
          maxLength: 16
          description: The page locale, as a BCP 47 tag.
          example: en-CA
        h3:
          type: string
          pattern: ^88[0-9a-f]{13}$
          description: >-
            The place in the event as a resolution-8 H3 cell. Send this or
            `lat`/`lng`, not both.
          example: 882b8e4a0dfffff
        lat:
          type: number
          minimum: -90
          maximum: 90
          description: >-
            Latitude of the place in the event. Reduced to a resolution-8 H3
            cell on receipt; never stored.
          example: 43.6532
        lng:
          type: number
          minimum: -180
          maximum: 180
          description: >-
            Longitude of the place in the event. Reduced to a resolution-8 H3
            cell on receipt; never stored.
          example: -79.3832
        surface:
          type: string
          enum:
            - home
            - results
            - listing
            - site_search
            - profile
            - widget
            - assistant
            - other
          description: Where on the site the list was drawn.
          example: results
        suppliers:
          type: array
          items:
            type: object
            properties:
              supplierId:
                type: string
                minLength: 1
                maxLength: 128
                description: >-
                  The MarketBox supplier id. Must belong to this project, or the
                  event is rejected.
                example: sup_01kv60qh3m7wznp8s0d2rk9abc
              position:
                type: integer
                minimum: 0
                description: >-
                  0-based rank in the list as drawn (the same number a search
                  response returns).
                example: 0
            required:
              - supplierId
              - position
            additionalProperties: false
          maxItems: 100
          description: >-
            The suppliers actually put on the page, in the order drawn, at most
            100. Every id must belong to this project, or the whole event is
            rejected.
          example:
            - supplierId: sup_01kv60qh3m7wznp8s0d2rk9abc
              position: 0
            - supplierId: sup_01kv60qh3m7wznp8s0d2rk9def
              position: 1
      required:
        - type
        - eventId
        - occurredAt
        - searchId
        - surface
        - suppliers
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key minted in the MarketBox dashboard. Scope is restricted to the
        projects you select at creation time. Every route needs the key's
        standard API access (`*`) except `POST /v1/projects/{projectId}/events`,
        which needs `events:write`; a key without `*` is refused with 403
        `CAPABILITY_NOT_GRANTED`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.