Manage availability schedules

Availability schedules define the hours when you’re bookable. Once created, you assign a schedule to an event type so it controls when that event can be booked. This guide shows you how to create, list, update, and delete schedules with the Cal ID API. All requests use the base URL https://api.cal.id and are authenticated with a Bearer token.

Create a schedule

Call POST /schedule/ with a JSON body. name is required; pass an optional timeZone to set the schedule’s default time zone.

curl -X POST https://api.cal.id/schedule/ \
  -H "Authorization: Bearer calid_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekday Working Hours",
    "timeZone": "Asia/Kolkata"
  }'

async function createSchedule() {
  const res = await fetch("https://api.cal.id/schedule/", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CALID_KEY}`,
      // Mandatory on POST/PATCH — without it the API returns 415.
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Weekday Working Hours",
      timeZone: "Asia/Kolkata",
    }),
  });

  const body = await res.json();
  if (!res.ok) throw new Error(body.message ?? `HTTP ${res.status}`);
  return body.data;
}

createSchedule().then((schedule) => console.log(schedule.id));

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]

response = requests.post(
    "https://api.cal.id/schedule/",
    headers={
        "Authorization": f"Bearer {CALID_KEY}",
        # Mandatory on POST/PATCH — without it the API returns 415.
        "Content-Type": "application/json",
    },
    json={
        "name": "Weekday Working Hours",
        "timeZone": "Asia/Kolkata",
    },
)
response.raise_for_status()

print(response.json()["data"]["id"])

On success, the created schedule is returned in data, including its id.

{
  "success": true,
  "data": {
    "id": 456,
    "name": "Weekday Working Hours",
    "timeZone": "Asia/Kolkata"
  },
  "message": "Schedule created successfully.",
  "meta": {}
}

List your schedules

Call GET /schedule/ to retrieve your schedules. This endpoint is not paginated — it returns every schedule in one response.

curl https://api.cal.id/schedule/ \
  -H "Authorization: Bearer calid_xxxxx"

async function listSchedules() {
  // No page/limit — this endpoint is not paginated and ignores them.
  const res = await fetch("https://api.cal.id/schedule/", {
    headers: { Authorization: `Bearer ${process.env.CALID_KEY}` },
  });

  const body = await res.json();
  if (!res.ok) throw new Error(body.message ?? `HTTP ${res.status}`);

  // data is the complete array; there is no meta object to read.
  return body.data;
}

listSchedules().then((schedules) =>
  console.log(schedules.map((s) => `${s.id} ${s.name}`))
);

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]

# No page/limit — this endpoint is not paginated and ignores them.
response = requests.get(
    "https://api.cal.id/schedule/",
    headers={"Authorization": f"Bearer {CALID_KEY}"},
)
response.raise_for_status()

# data is the complete list; there is no meta object to read.
for schedule in response.json()["data"]:
    print(schedule["id"], schedule["name"])

Your schedules are returned as an array in data. The response carries success, data, and message — there is no meta object.

GET /schedule/ accepts page and limit in the query string without erroring, but ignores them: ?limit=1 still returns the complete list. Do not write a paging loop against this endpoint — it will re-read the same full list forever. The same applies to GET /teams/\{teamId\}/schedules.

Update or delete a schedule

Use the schedule’s id to change or remove it. Call PATCH /schedule/\{scheduleId\} with the fields you want to update.

curl -X PATCH https://api.cal.id/schedule/456 \
  -H "Authorization: Bearer calid_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekday Working Hours (IST)"
  }'

const scheduleId = 456;

async function updateSchedule() {
  const res = await fetch(`https://api.cal.id/schedule/${scheduleId}`, {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.CALID_KEY}`,
      // Mandatory on POST/PATCH — without it the API returns 415.
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "Weekday Working Hours (IST)" }),
  });

  const body = await res.json();
  if (!res.ok) throw new Error(body.message ?? `HTTP ${res.status}`);
  return body.data;
}

updateSchedule().then((schedule) => console.log(schedule));

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]
schedule_id = 456

response = requests.patch(
    f"https://api.cal.id/schedule/{schedule_id}",
    headers={
        "Authorization": f"Bearer {CALID_KEY}",
        # Mandatory on POST/PATCH — without it the API returns 415.
        "Content-Type": "application/json",
    },
    json={"name": "Weekday Working Hours (IST)"},
)
response.raise_for_status()

print(response.json()["data"])

To remove a schedule, call DELETE /schedule/\{scheduleId\}.

curl -X DELETE https://api.cal.id/schedule/456 \
  -H "Authorization: Bearer calid_xxxxx"

const scheduleId = 456;

async function deleteSchedule() {
  const res = await fetch(`https://api.cal.id/schedule/${scheduleId}`, {
    method: "DELETE",
    headers: { Authorization: `Bearer ${process.env.CALID_KEY}` },
  });

  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new Error(body.message ?? `HTTP ${res.status}`);
  }

  console.log("Schedule deleted");
}

deleteSchedule();

import os
import requests

CALID_KEY = os.environ["CALID_KEY"]
schedule_id = 456

response = requests.delete(
    f"https://api.cal.id/schedule/{schedule_id}",
    headers={"Authorization": f"Bearer {CALID_KEY}"},
)
response.raise_for_status()

print("Schedule deleted")

Creating a schedule doesn’t affect bookings on its own. To make a schedule apply, assign it to an event type — see Set availability for an event type.

Schedule endpoint reference

Create a schedule — full endpoint reference

Get started

Guides

Manage availability schedules

Schedule endpoint reference

​Schedule endpoint reference

Schedule endpoint reference