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

# Generate clustered time slots from suppliers + engine config

> Runs the clustering engine directly on suppliers and a config YOU supply. Nothing is read from the project — not the catalogue, not the supplier roster, not existing bookings — so this answers "what would the engine do with these inputs", not "when is this bookable". The supplier availability you pass is taken at face value, which means it will happily return slots for people who are already booked; never drive a booking flow from it. Use /availability/search, or /availability/suppliers for a supplier-centric view, for anything a client sees.

It exists for tuning and diagnosis: `metrics` and `kpis` in the response let you compare configs against a fixed input set, and replaying a captured payload reproduces a result (see the note on `metrics` below for when it does not). `config` is passed through to the engine largely unvalidated, so a malformed knob tends to surface as poor output or an entry in `errors` rather than a 400 — and as with the other availability routes, `errors` arrives inside a 200.

`metrics.totalTravelTimeRequestsMade` is the number of distinct drives (direction, place) answered for this request, shared across all suppliers; a failed or unroutable drive is not counted.

History: counts and slot distances changed on 2026-11-12 (routing in shared rounds). A payload captured before then can replay with different counts, distances and labels, and can gain slots.

The response carries a `searchId` (also the `X-MB-Search-Id` header) like every search route, but nothing is logged for insights: the suppliers and config are yours, not the project's.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/availability/time-slots
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}/availability/time-slots:
    post:
      tags:
        - Availability
      summary: Generate clustered time slots from suppliers + engine config
      description: >-
        Runs the clustering engine directly on suppliers and a config YOU
        supply. Nothing is read from the project — not the catalogue, not the
        supplier roster, not existing bookings — so this answers "what would the
        engine do with these inputs", not "when is this bookable". The supplier
        availability you pass is taken at face value, which means it will
        happily return slots for people who are already booked; never drive a
        booking flow from it. Use /availability/search, or
        /availability/suppliers for a supplier-centric view, for anything a
        client sees.


        It exists for tuning and diagnosis: `metrics` and `kpis` in the response
        let you compare configs against a fixed input set, and replaying a
        captured payload reproduces a result (see the note on `metrics` below
        for when it does not). `config` is passed through to the engine largely
        unvalidated, so a malformed knob tends to surface as poor output or an
        entry in `errors` rather than a 400 — and as with the other availability
        routes, `errors` arrives inside a 200.


        `metrics.totalTravelTimeRequestsMade` is the number of distinct drives
        (direction, place) answered for this request, shared across all
        suppliers; a failed or unroutable drive is not counted.


        History: counts and slot distances changed on 2026-11-12 (routing in
        shared rounds). A payload captured before then can replay with different
        counts, distances and labels, and can gain slots.


        The response carries a `searchId` (also the `X-MB-Search-Id` header)
        like every search route, but nothing is logged for insights: the
        suppliers and config are yours, not the project's.
      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
      requestBody:
        description: Suppliers + engine config
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                config:
                  type: object
                  properties: {}
                  additionalProperties:
                    nullable: true
                suppliers:
                  type: array
                  items:
                    type: object
                    properties:
                      supplierId:
                        type: string
                      maxTravelTimeMins:
                        type: number
                      bufferTimeMins:
                        type: number
                      availability:
                        type: array
                        items:
                          type: object
                          properties:
                            startDateAndTime:
                              type: string
                            endDateAndTime:
                              type: string
                            rrule:
                              type: string
                            startGeoLocation:
                              type: array
                              items:
                                type: number
                              minItems: 2
                              maxItems: 2
                            endGeoLocation:
                              type: array
                              items:
                                type: number
                              minItems: 2
                              maxItems: 2
                            timezone:
                              type: string
                          required:
                            - startDateAndTime
                            - endDateAndTime
                      bookings:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            startDateAndTime:
                              type: string
                            durationMins:
                              type: number
                            geoLocation:
                              type: array
                              nullable: true
                              items:
                                type: number
                              minItems: 2
                              maxItems: 2
                            isGeoAnchoring:
                              type: boolean
                          required:
                            - startDateAndTime
                            - durationMins
                      blockedTime:
                        type: array
                        items:
                          type: object
                          properties:
                            startDateAndTime:
                              type: string
                            endDateAndTime:
                              type: string
                            rrule:
                              type: string
                              nullable: true
                          required:
                            - startDateAndTime
                            - endDateAndTime
                      maxTravelTimeFromStartGeoLocationMins:
                        type: number
                        nullable: true
                      maxTravelTimeToEndGeoLocationMins:
                        type: number
                        nullable: true
                      timezone:
                        type: string
                    required:
                      - supplierId
                      - maxTravelTimeMins
                      - availability
              required:
                - config
                - suppliers
      responses:
        '200':
          description: Suggested slots + metrics/kpis
          content:
            application/json:
              schema:
                type: object
                properties:
                  searchId:
                    type: string
                    description: >-
                      The id of this search, also returned as the
                      `X-MB-Search-Id` header. Every page of a paginated search
                      carries the same id (the cursor keeps it). Keep it for the
                      session if you want attribution: pass it back as
                      `searchId` when the client books, and in the
                      `search.rendered` event when you report what you showed.
                    example: srch_01k7q3x9h4e8rb2d6m0z5a7c1n
                  status:
                    type: string
                  timeSlots:
                    type: array
                    items:
                      nullable: true
                    description: >-
                      Clustered suggested slots. Each entry carries
                      `timeSlotDateAndTime` (the slot instant rendered in the
                      response `timezone`, with that zone's offset at that
                      instant — R-30) and `timeSlotStartUtc` (the same instant
                      in UTC, `Z` — R-31, always present, always the same
                      instant as `timeSlotDateAndTime`). Prefer
                      `timeSlotStartUtc` as the booking anchor.
                  errors:
                    type: array
                    items:
                      type: string
                  metrics:
                    nullable: true
                  kpis:
                    nullable: true
                required:
                  - searchId
                  - status
                  - timeSlots
                  - errors
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: API key cannot access this project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    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
  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.