coss.comdocs

Explain a slot

GET
/v1/scheduling/event_types/{event_type}/slots/explain

Why one start can or can't be booked right now, host by host, decided the same way a booking is. For support and debugging: it says when a host is busy, so don't show it to attendees.

Authorization

bearerAuth
headerAuthorizationBearer <token>

A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.

Path Parameters

event_type*string

The event type's id or uid.

Query Parameters

start*string

An ISO 8601 instant with an offset.

host?string

Only this host (id or uid).

duration_minutes?integer
Range5 <= value <= 1440
attributes?string

A JSON object narrowing a pool, such as {"licensed_in":"CA"}.

Header Parameters

Coss-Version?"2026-10-10"

The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.

Value in"2026-10-10"

Response Body

Whether it can be booked, and why.

application/json
  1. response
object*"scheduling.slot_explanation"
Value in"scheduling.slot_explanation"
start*string

The start asked about.

end*string

When it would end.

available*boolean

Whether it can be booked right now.

reason*|

Why it can't: not_on_grid, too_soon, outside_booking_window, calendar_unverified, outside_availability, host_busy, already_claimed, limit_reached or session_full, or event_type_inactive or no_hosts. null when it can. With several hosts refused, the first one's reason: see hosts.

hosts*array<>

Everyone who could take this event type, narrowed by the query.

import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.scheduling.slots.explain({  value: "evtype_01kd2m9a0b1c2d3e4f5g6h7j8m",}, {  start: "2027-01-04T15:00:00.000Z",});
{  "object": "scheduling.slot_explanation",  "start": "2027-01-04T15:00:00.000Z",  "end": "2027-01-04T15:30:00.000Z",  "available": false,  "reason": "host_busy",  "hosts": [    {      "host": "host_01kd2m9a0b1c2d3e4f5g6h7j8m",      "role": "member",      "available": false,      "reason": "host_busy",      "calendar_reason": null    }  ]}