Schedule API Reference

Complete API reference for the Schedule resource in the beeps SDK.

Schedule Methods

`client.schedule.create(input)`

Create a new schedule.

Parameters:

input: CreateScheduleInput

Returns: Promise<Schedule>

Example:

const schedule = await client.schedule.create({
  name: "Weekly On-Call",
  relayId: "rly_abc123",
  type: "weekly",
  startDay: "monday",
  startTime: "09:00",
  externalKey: "prod-oncall",
});

`client.schedule.list()`

List all schedules in your organization.

Returns: Promise<Schedule[]>

Example:

const schedules = await client.schedule.list();

`client.schedule.addMember(scheduleId, input)`

Add a team member to a schedule rotation. The member will join at the next rotation boundary, not immediately. This preserves the current on-call assignment.

Parameters:

scheduleId: string
input: AddScheduleMemberInput

Returns: Promise<ScheduleMember>

Example:

const member = await client.schedule.addMember("sch_xyz789", {
  userId: "usr_alice",
});
// Alice joins the rotation at the next shift boundary

`client.schedule.listMembers(scheduleId)`

List active members of a schedule rotation.

Parameters:

scheduleId: string

Returns: Promise<ScheduleMember[]>

Example:

const members = await client.schedule.listMembers("sch_xyz789");

`client.schedule.listMembersSafe(scheduleId)`

List active schedule members without throwing exceptions.

Parameters:

scheduleId: string

Returns: Promise<Result<ScheduleMember[]>>

Example:

const result = await client.schedule.listMembersSafe("sch_xyz789");

if (result.error) {
  console.error("Error:", result.error.message);
} else {
  console.log(`Members: ${result.data.length}`);
}

`client.schedule.removeMember(scheduleId, userId)`

Remove a team member from a schedule rotation. The member will remain on-call through the end of their current shift, then be removed at the next rotation boundary. Cannot remove a member if it would leave the schedule with no active members.

Parameters:

scheduleId: string
userId: string

Returns: Promise<ScheduleMember>

Example:

const member = await client.schedule.removeMember("sch_xyz789", "usr_alice");
// Alice completes her current shift, then leaves the rotation

`client.schedule.getAssignments(scheduleId, params?)`

Get schedule assignments.

Parameters:

scheduleId: string
params?: GetAssignmentsParams

Returns: Promise<ScheduleAssignment[]>

Examples:

// Get next 5 assignments
const assignments = await client.schedule.getAssignments("sch_xyz789", {
  type: "assignments",
  count: 5,
});

// Get assignments for next 14 days
const assignments = await client.schedule.getAssignments("sch_xyz789", {
  type: "days",
  count: 14,
});

// Get assignments until specific date (using Date object)
const assignments = await client.schedule.getAssignments("sch_xyz789", {
  type: "until",
  date: new Date("2025-12-31T23:59:59.999Z"),
});

// Or using ISO 8601 string with Z suffix (UTC timezone required)
const assignments = await client.schedule.getAssignments("sch_xyz789", {
  type: "until",
  date: "2025-12-31T23:59:59.999Z",
});

`client.schedule.getOnCall(scheduleId)`

Get the user currently on-call for a schedule.

Parameters:

scheduleId: string

Returns: Promise<BeepsUser>

Example:

const onCall = await client.schedule.getOnCall("sch_xyz789");
console.log(`${onCall.email} is on-call`);

`client.schedule.getOnCallSafe(scheduleId)`

Get the user currently on-call without throwing exceptions.

Parameters:

scheduleId: string

Returns: Promise<Result<BeepsUser>>

Example:

const result = await client.schedule.getOnCallSafe("sch_xyz789");

if (result.error) {
  console.error("Error:", result.error.message);
} else {
  console.log(`On-call: ${result.data.email}`);
}

Override Methods

`client.schedule.createOverride(scheduleId, input)`

Create a temporary on-call override. The override user takes over for the specified time window.

Parameters:

scheduleId: string
input: CreateScheduleOverrideInput

Returns: Promise<ScheduleOverride>

Example:

const override = await client.schedule.createOverride("sch_xyz789", {
  userId: "usr_bob",
  startAt: "2025-03-15T09:00:00.000Z",
  endAt: "2025-03-22T09:00:00.000Z",
  reason: "Vacation coverage",
});

`client.schedule.listOverrides(scheduleId, params?)`

List overrides for a schedule, optionally filtered by date range.

Parameters:

scheduleId: string
params?: ListScheduleOverridesParams

Returns: Promise<ScheduleOverride[]>

Example:

const overrides = await client.schedule.listOverrides("sch_xyz789");

// With date range filter
const overrides = await client.schedule.listOverrides("sch_xyz789", {
  startAt: "2025-03-01T00:00:00.000Z",
  endAt: "2025-03-31T23:59:59.999Z",
});

`client.schedule.updateOverride(scheduleId, overrideId, input)`

Update an existing override. All fields are optional.

Parameters:

scheduleId: string
overrideId: string
input: UpdateScheduleOverrideInput

Returns: Promise<ScheduleOverride>

Example:

const updated = await client.schedule.updateOverride("sch_xyz789", "ovr_abc123", {
  endAt: "2025-03-25T09:00:00.000Z",
  reason: "Extended coverage",
});

`client.schedule.cancelOverride(scheduleId, overrideId)`

Cancel an override. The normal rotation resumes.

Parameters:

scheduleId: string
overrideId: string

Returns: Promise<ScheduleOverride>

Example:

const canceled = await client.schedule.cancelOverride("sch_xyz789", "ovr_abc123");

Types

CreateScheduleInput

type CreateScheduleInput = {
  name: string;
  relayId: string;
  type: "daily" | "weekly";
  startDay:
    | "monday"
    | "tuesday"
    | "wednesday"
    | "thursday"
    | "friday"
    | "saturday"
    | "sunday";
  startTime: string; // HH:MM format (24-hour)
  externalKey?: string;
};

Schedule

type Schedule = {
  id: string;
  organizationId: string;
  relayId: string;
  name: string;
  type: "daily" | "weekly";
  startDay:
    | "monday"
    | "tuesday"
    | "wednesday"
    | "thursday"
    | "friday"
    | "saturday"
    | "sunday";
  startTime: string;
  externalKey: string | null;
  createdAt: string;
  updatedAt: string;
  deletedAt: string | null;
};

AddScheduleMemberInput

type AddScheduleMemberInput = {
  userId: string;
};

ScheduleMember

type ScheduleMember = {
  scheduleId: string;
  userId: string;
  createdAt?: string;
  effectiveAt?: string;
  removedAt?: string | null;
};

GetAssignmentsParams

type GetAssignmentsParams =
  | { type?: "assignments"; count?: number }
  | { type: "until"; date: string | Date }
  | { type: "days"; count: number };

Note: When using type: "until", the date parameter must be either:

A JavaScript Date object (automatically converted to UTC ISO 8601 format)
An ISO 8601 timestamp string with Z suffix (e.g., "2025-12-31T23:59:59.999Z")

The SDK validates that string dates include the Z suffix to ensure UTC timezone consistency. Dates without timezone indicators will be rejected with a clear error message.

ScheduleAssignment

type ScheduleAssignment = {
  userId: string;
  startDate: string; // ISO 8601 timestamp
  endDate: string; // ISO 8601 timestamp
  assignmentNumber: number;
};

BeepsUser

type BeepsUser = {
  userId: string;
  email: string;
  assignmentNumber: number | null; // Null when schedule has no members
  scheduleId: string;
  isOverride?: boolean; // True if user is on-call via schedule override
  overrideId?: string; // ID of the schedule override (if applicable)
};

CreateScheduleOverrideInput

type CreateScheduleOverrideInput = {
  userId: string;
  startAt: string | Date;
  endAt: string | Date;
  reason?: string;
};

UpdateScheduleOverrideInput

type UpdateScheduleOverrideInput = {
  startAt?: string | Date;
  endAt?: string | Date;
  reason?: string;
};

ListScheduleOverridesParams

type ListScheduleOverridesParams = {
  startAt?: string | Date;
  endAt?: string | Date;
};

ScheduleOverride

type ScheduleOverride = {
  id: string;
  organizationId: string;
  scheduleId: string;
  userId: string;
  startAt: string;
  endAt: string;
  reason: string | null;
  createdByUserId: string;
  createdAt: string;
  updatedAt: string;
  canceledAt: string | null;
  deletedAt: string | null;
};

HTTP Endpoints

Create Schedule

POST /v0/schedule

Request Body:

{
  "name": "Weekly On-Call",
  "relayId": "rly_abc123",
  "type": "weekly",
  "startDay": "monday",
  "startTime": "09:00",
  "externalKey": "prod-oncall"
}

List Schedules

GET /v0/schedule

Add Schedule Member

POST /v0/schedule/:scheduleId/members

Adds a member to the rotation. They will join at the next rotation boundary.

Request Body:

{
  "userId": "usr_alice"
}

List Schedule Members

GET /v0/schedule/:scheduleId/members

Remove Schedule Member

DELETE /v0/schedule/:scheduleId/members/:userId

Removes a member from the rotation. They will complete their current shift and leave at the next rotation boundary. Cannot remove a member if it would leave the schedule with no active members.

Get Assignments

GET /v0/schedule/:scheduleId/assignments
GET /v0/schedule/:scheduleId/assignments?type=assignments&count=5
GET /v0/schedule/:scheduleId/assignments?type=days&count=14
GET /v0/schedule/:scheduleId/assignments?type=until&date=2025-12-31T23:59:59.999Z

Note: The date parameter for type=until must be a valid ISO 8601 timestamp with Z suffix (UTC timezone). Dates without the Z suffix will be rejected with a validation error.

Get Current On-Call User

GET /v0/schedule/:scheduleId/on-call

Create Override

POST /v0/schedule/:scheduleId/overrides

Request Body:

{
  "userId": "usr_bob",
  "startAt": "2025-03-15T09:00:00.000Z",
  "endAt": "2025-03-22T09:00:00.000Z",
  "reason": "Vacation coverage"
}

Note: startAt and endAt must be valid ISO 8601 timestamps with Z suffix (UTC timezone).

List Overrides

GET /v0/schedule/:scheduleId/overrides
GET /v0/schedule/:scheduleId/overrides?startAt=2025-03-01T00:00:00.000Z&endAt=2025-03-31T23:59:59.999Z

Update Override

PATCH /v0/schedule/:scheduleId/overrides/:overrideId

Request Body:

{
  "endAt": "2025-03-25T09:00:00.000Z",
  "reason": "Extended coverage"
}

Cancel Override

DELETE /v0/schedule/:scheduleId/overrides/:overrideId

Authentication

All API requests require authentication using your API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.beeps.dev/v0/schedule