Search availability across hosts

POST
/v1/scheduling/availability/search

For "who's free" pages: each matching host's soonest slots, soonest first, across up to 500 hosts.

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

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"

Request Body

application/json
  1. body
event_type*string

The event type's id or uid.

start*string

An ISO 8601 instant with an offset.

end*string

An ISO 8601 instant with an offset.

attributes?

Only hosts matching all of these.

hosts?array<string>

Only these hosts (ids or uids). Default: everyone the event type could offer.

Itemsitems <= 500
slots_per_host?integer

How many of each host's soonest slots to return.

Range1 <= value <= 50
Default3
limit?integer

Hosts to return, soonest availability first.

Range1 <= value <= 500
Default50

Response Body

Hosts with slots.

application/json
  1. response
object*"list"
Value in"list"
data*array<>

Each host with availability, soonest first.

has_more*boolean

Whether more hosts matched than limit returned.

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.availability.search({  event_type: "evtype_01kd2m9a0b1c2d3e4f5g6h7j8m",  start: "2027-01-04T00:00:00.000Z",  end: "2027-01-18T00:00:00.000Z",  attributes: {    licensed_in: "CA",  },});
{  "object": "list",  "data": [    {      "host": "host_01kd2m9a0b1c2d3e4f5g6h7j8m",      "uid": "doctor_482",      "slots": [        {          "start": "2027-01-04T15:00:00.000Z",          "end": "2027-01-04T15:30:00.000Z"        }      ]    }  ],  "has_more": false}