Schedule API Reference

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

If you omit startAt when creating a schedule, the server defaults it to the current time so the schedule starts immediately.

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",
  handoffDay: "monday",
  handoffTime: "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. New members usually join at the next handoff boundary so the current on-call assignment is not interrupted. If the schedule has not started yet, they become active at startAt. If the schedule is active but currently has no active members, they become active immediately.

Parameters:

scheduleId: string
input: AddScheduleMemberInput

Returns: Promise<ScheduleMember>

Examples:

// Add by email address
const member = await client.schedule.addMember("sch_xyz789", {
  email: "alice@example.com",
});

// Or add by user ID
const member = await client.schedule.addMember("sch_xyz789", {
  userId: "usr_alice",
});
// Alice joins based on the schedule timing

`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";
  handoffDay:
    | "monday"
    | "tuesday"
    | "wednesday"
    | "thursday"
    | "friday"
    | "saturday"
    | "sunday";
  handoffTime: string; // HH:MM format (24-hour)
  startAt?: string | Date;
  externalKey?: string;
};

Schedule

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

AddScheduleMemberInput

type AddScheduleMemberInput =
  | { userId: string }
  | { email: string };

ScheduleMember

type ScheduleMember = {
  id?: string;
  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; // Generated assignment index, 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",
  "handoffDay": "monday",
  "handoffTime": "09:00",
  "externalKey": "prod-oncall"
}

If startAt is omitted, the server sets it to the current time.

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. Pass either userId or email.

Request Body:

{
  "email": "alice@example.com"
}

Or by user ID:

{
  "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