curl --request POST \
--url https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/time-slots \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"config": {},
"suppliers": [
{
"supplierId": "<string>",
"maxTravelTimeMins": 123,
"availability": [
{
"startDateAndTime": "<string>",
"endDateAndTime": "<string>",
"rrule": "<string>",
"startGeoLocation": [
123
],
"endGeoLocation": [
123
],
"timezone": "<string>"
}
],
"bufferTimeMins": 123,
"bookings": [
{
"startDateAndTime": "<string>",
"durationMins": 123,
"id": "<string>",
"geoLocation": [
123
],
"isGeoAnchoring": true
}
],
"blockedTime": [
{
"startDateAndTime": "<string>",
"endDateAndTime": "<string>",
"rrule": "<string>"
}
],
"maxTravelTimeFromStartGeoLocationMins": 123,
"maxTravelTimeToEndGeoLocationMins": 123,
"timezone": "<string>"
}
]
}
'import requests
url = "https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/time-slots"
payload = {
"config": {},
"suppliers": [
{
"supplierId": "<string>",
"maxTravelTimeMins": 123,
"availability": [
{
"startDateAndTime": "<string>",
"endDateAndTime": "<string>",
"rrule": "<string>",
"startGeoLocation": [123],
"endGeoLocation": [123],
"timezone": "<string>"
}
],
"bufferTimeMins": 123,
"bookings": [
{
"startDateAndTime": "<string>",
"durationMins": 123,
"id": "<string>",
"geoLocation": [123],
"isGeoAnchoring": True
}
],
"blockedTime": [
{
"startDateAndTime": "<string>",
"endDateAndTime": "<string>",
"rrule": "<string>"
}
],
"maxTravelTimeFromStartGeoLocationMins": 123,
"maxTravelTimeToEndGeoLocationMins": 123,
"timezone": "<string>"
}
]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
config: {},
suppliers: [
{
supplierId: '<string>',
maxTravelTimeMins: 123,
availability: [
{
startDateAndTime: '<string>',
endDateAndTime: '<string>',
rrule: '<string>',
startGeoLocation: [123],
endGeoLocation: [123],
timezone: '<string>'
}
],
bufferTimeMins: 123,
bookings: [
{
startDateAndTime: '<string>',
durationMins: 123,
id: '<string>',
geoLocation: [123],
isGeoAnchoring: true
}
],
blockedTime: [{startDateAndTime: '<string>', endDateAndTime: '<string>', rrule: '<string>'}],
maxTravelTimeFromStartGeoLocationMins: 123,
maxTravelTimeToEndGeoLocationMins: 123,
timezone: '<string>'
}
]
})
};
fetch('https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/time-slots', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/time-slots",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'config' => [
],
'suppliers' => [
[
'supplierId' => '<string>',
'maxTravelTimeMins' => 123,
'availability' => [
[
'startDateAndTime' => '<string>',
'endDateAndTime' => '<string>',
'rrule' => '<string>',
'startGeoLocation' => [
123
],
'endGeoLocation' => [
123
],
'timezone' => '<string>'
]
],
'bufferTimeMins' => 123,
'bookings' => [
[
'startDateAndTime' => '<string>',
'durationMins' => 123,
'id' => '<string>',
'geoLocation' => [
123
],
'isGeoAnchoring' => true
]
],
'blockedTime' => [
[
'startDateAndTime' => '<string>',
'endDateAndTime' => '<string>',
'rrule' => '<string>'
]
],
'maxTravelTimeFromStartGeoLocationMins' => 123,
'maxTravelTimeToEndGeoLocationMins' => 123,
'timezone' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/time-slots"
payload := strings.NewReader("{\n \"config\": {},\n \"suppliers\": [\n {\n \"supplierId\": \"<string>\",\n \"maxTravelTimeMins\": 123,\n \"availability\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"endDateAndTime\": \"<string>\",\n \"rrule\": \"<string>\",\n \"startGeoLocation\": [\n 123\n ],\n \"endGeoLocation\": [\n 123\n ],\n \"timezone\": \"<string>\"\n }\n ],\n \"bufferTimeMins\": 123,\n \"bookings\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"durationMins\": 123,\n \"id\": \"<string>\",\n \"geoLocation\": [\n 123\n ],\n \"isGeoAnchoring\": true\n }\n ],\n \"blockedTime\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"endDateAndTime\": \"<string>\",\n \"rrule\": \"<string>\"\n }\n ],\n \"maxTravelTimeFromStartGeoLocationMins\": 123,\n \"maxTravelTimeToEndGeoLocationMins\": 123,\n \"timezone\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/time-slots")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"config\": {},\n \"suppliers\": [\n {\n \"supplierId\": \"<string>\",\n \"maxTravelTimeMins\": 123,\n \"availability\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"endDateAndTime\": \"<string>\",\n \"rrule\": \"<string>\",\n \"startGeoLocation\": [\n 123\n ],\n \"endGeoLocation\": [\n 123\n ],\n \"timezone\": \"<string>\"\n }\n ],\n \"bufferTimeMins\": 123,\n \"bookings\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"durationMins\": 123,\n \"id\": \"<string>\",\n \"geoLocation\": [\n 123\n ],\n \"isGeoAnchoring\": true\n }\n ],\n \"blockedTime\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"endDateAndTime\": \"<string>\",\n \"rrule\": \"<string>\"\n }\n ],\n \"maxTravelTimeFromStartGeoLocationMins\": 123,\n \"maxTravelTimeToEndGeoLocationMins\": 123,\n \"timezone\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/time-slots")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"config\": {},\n \"suppliers\": [\n {\n \"supplierId\": \"<string>\",\n \"maxTravelTimeMins\": 123,\n \"availability\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"endDateAndTime\": \"<string>\",\n \"rrule\": \"<string>\",\n \"startGeoLocation\": [\n 123\n ],\n \"endGeoLocation\": [\n 123\n ],\n \"timezone\": \"<string>\"\n }\n ],\n \"bufferTimeMins\": 123,\n \"bookings\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"durationMins\": 123,\n \"id\": \"<string>\",\n \"geoLocation\": [\n 123\n ],\n \"isGeoAnchoring\": true\n }\n ],\n \"blockedTime\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"endDateAndTime\": \"<string>\",\n \"rrule\": \"<string>\"\n }\n ],\n \"maxTravelTimeFromStartGeoLocationMins\": 123,\n \"maxTravelTimeToEndGeoLocationMins\": 123,\n \"timezone\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"searchId": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n",
"status": "<string>",
"timeSlots": [
null
],
"errors": [
"<string>"
],
"metrics": null,
"kpis": null
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}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.
curl --request POST \
--url https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/time-slots \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"config": {},
"suppliers": [
{
"supplierId": "<string>",
"maxTravelTimeMins": 123,
"availability": [
{
"startDateAndTime": "<string>",
"endDateAndTime": "<string>",
"rrule": "<string>",
"startGeoLocation": [
123
],
"endGeoLocation": [
123
],
"timezone": "<string>"
}
],
"bufferTimeMins": 123,
"bookings": [
{
"startDateAndTime": "<string>",
"durationMins": 123,
"id": "<string>",
"geoLocation": [
123
],
"isGeoAnchoring": true
}
],
"blockedTime": [
{
"startDateAndTime": "<string>",
"endDateAndTime": "<string>",
"rrule": "<string>"
}
],
"maxTravelTimeFromStartGeoLocationMins": 123,
"maxTravelTimeToEndGeoLocationMins": 123,
"timezone": "<string>"
}
]
}
'import requests
url = "https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/time-slots"
payload = {
"config": {},
"suppliers": [
{
"supplierId": "<string>",
"maxTravelTimeMins": 123,
"availability": [
{
"startDateAndTime": "<string>",
"endDateAndTime": "<string>",
"rrule": "<string>",
"startGeoLocation": [123],
"endGeoLocation": [123],
"timezone": "<string>"
}
],
"bufferTimeMins": 123,
"bookings": [
{
"startDateAndTime": "<string>",
"durationMins": 123,
"id": "<string>",
"geoLocation": [123],
"isGeoAnchoring": True
}
],
"blockedTime": [
{
"startDateAndTime": "<string>",
"endDateAndTime": "<string>",
"rrule": "<string>"
}
],
"maxTravelTimeFromStartGeoLocationMins": 123,
"maxTravelTimeToEndGeoLocationMins": 123,
"timezone": "<string>"
}
]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
config: {},
suppliers: [
{
supplierId: '<string>',
maxTravelTimeMins: 123,
availability: [
{
startDateAndTime: '<string>',
endDateAndTime: '<string>',
rrule: '<string>',
startGeoLocation: [123],
endGeoLocation: [123],
timezone: '<string>'
}
],
bufferTimeMins: 123,
bookings: [
{
startDateAndTime: '<string>',
durationMins: 123,
id: '<string>',
geoLocation: [123],
isGeoAnchoring: true
}
],
blockedTime: [{startDateAndTime: '<string>', endDateAndTime: '<string>', rrule: '<string>'}],
maxTravelTimeFromStartGeoLocationMins: 123,
maxTravelTimeToEndGeoLocationMins: 123,
timezone: '<string>'
}
]
})
};
fetch('https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/time-slots', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/time-slots",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'config' => [
],
'suppliers' => [
[
'supplierId' => '<string>',
'maxTravelTimeMins' => 123,
'availability' => [
[
'startDateAndTime' => '<string>',
'endDateAndTime' => '<string>',
'rrule' => '<string>',
'startGeoLocation' => [
123
],
'endGeoLocation' => [
123
],
'timezone' => '<string>'
]
],
'bufferTimeMins' => 123,
'bookings' => [
[
'startDateAndTime' => '<string>',
'durationMins' => 123,
'id' => '<string>',
'geoLocation' => [
123
],
'isGeoAnchoring' => true
]
],
'blockedTime' => [
[
'startDateAndTime' => '<string>',
'endDateAndTime' => '<string>',
'rrule' => '<string>'
]
],
'maxTravelTimeFromStartGeoLocationMins' => 123,
'maxTravelTimeToEndGeoLocationMins' => 123,
'timezone' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/time-slots"
payload := strings.NewReader("{\n \"config\": {},\n \"suppliers\": [\n {\n \"supplierId\": \"<string>\",\n \"maxTravelTimeMins\": 123,\n \"availability\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"endDateAndTime\": \"<string>\",\n \"rrule\": \"<string>\",\n \"startGeoLocation\": [\n 123\n ],\n \"endGeoLocation\": [\n 123\n ],\n \"timezone\": \"<string>\"\n }\n ],\n \"bufferTimeMins\": 123,\n \"bookings\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"durationMins\": 123,\n \"id\": \"<string>\",\n \"geoLocation\": [\n 123\n ],\n \"isGeoAnchoring\": true\n }\n ],\n \"blockedTime\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"endDateAndTime\": \"<string>\",\n \"rrule\": \"<string>\"\n }\n ],\n \"maxTravelTimeFromStartGeoLocationMins\": 123,\n \"maxTravelTimeToEndGeoLocationMins\": 123,\n \"timezone\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/time-slots")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"config\": {},\n \"suppliers\": [\n {\n \"supplierId\": \"<string>\",\n \"maxTravelTimeMins\": 123,\n \"availability\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"endDateAndTime\": \"<string>\",\n \"rrule\": \"<string>\",\n \"startGeoLocation\": [\n 123\n ],\n \"endGeoLocation\": [\n 123\n ],\n \"timezone\": \"<string>\"\n }\n ],\n \"bufferTimeMins\": 123,\n \"bookings\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"durationMins\": 123,\n \"id\": \"<string>\",\n \"geoLocation\": [\n 123\n ],\n \"isGeoAnchoring\": true\n }\n ],\n \"blockedTime\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"endDateAndTime\": \"<string>\",\n \"rrule\": \"<string>\"\n }\n ],\n \"maxTravelTimeFromStartGeoLocationMins\": 123,\n \"maxTravelTimeToEndGeoLocationMins\": 123,\n \"timezone\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://apiv2.gomarketbox.com/v1/projects/{projectId}/availability/time-slots")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"config\": {},\n \"suppliers\": [\n {\n \"supplierId\": \"<string>\",\n \"maxTravelTimeMins\": 123,\n \"availability\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"endDateAndTime\": \"<string>\",\n \"rrule\": \"<string>\",\n \"startGeoLocation\": [\n 123\n ],\n \"endGeoLocation\": [\n 123\n ],\n \"timezone\": \"<string>\"\n }\n ],\n \"bufferTimeMins\": 123,\n \"bookings\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"durationMins\": 123,\n \"id\": \"<string>\",\n \"geoLocation\": [\n 123\n ],\n \"isGeoAnchoring\": true\n }\n ],\n \"blockedTime\": [\n {\n \"startDateAndTime\": \"<string>\",\n \"endDateAndTime\": \"<string>\",\n \"rrule\": \"<string>\"\n }\n ],\n \"maxTravelTimeFromStartGeoLocationMins\": 123,\n \"maxTravelTimeToEndGeoLocationMins\": 123,\n \"timezone\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"searchId": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n",
"status": "<string>",
"timeSlots": [
null
],
"errors": [
"<string>"
],
"metrics": null,
"kpis": null
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}Authorizations
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.
Path Parameters
Body
Suppliers + engine config
Response
Suggested slots + metrics/kpis
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.
"srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
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.