Skip to main content
POST
Create schedule

Restrictions

Usage

  • schedule_name (or the legacy name) is required, at most 40 characters, and must be unique in the account. description is at most 500 characters.
  • time_zone anchors every wall-clock rule of the schedule (handoff time, restriction windows, weekdays, fixed-time notifications) and cannot be changed later. When omitted, the schedule is evaluated in Asia/Shanghai and time_zone reads back as an empty string.
  • Layer times can be sent either as numbers (layer_start, handoff_time, restrict_periods, …) or as wall-clock strings (starts_at, ends_at, handoff, restricts_wall); wall-clock fields win and are converted in the schedule’s time zone.
  • Creating more schedules than the account’s plan allows is rejected with NoLicense.
  • Use /schedule/preview to check the resulting shifts before saving.
  • Every call is recorded in the account audit log.
  • The caller must be the account owner or an admin, or belong to team_id; a schedule without a team can be created by anyone. Otherwise the call returns AccessDenied.
  • A person ID that is not a member of the account, or an IM data source outside the account, returns InvalidParameter; a newly added IM app target can return NoLicense.

Authorizations

app_key
string
query
required

APP Key created in the Flashduty console under My → APP Key. Send it as the app_key query parameter or in the Fd-App-Key request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret.

Body

application/json

Request body of /schedule/create, /schedule/update and /schedule/preview. schedule_name (or the legacy name) is required on create, schedule_id on update, and start/end on preview.

schedule_id
integer<int64> | null

Schedule ID, required on update; obtain it from POST /schedule/list.

schedule_name
string | null

Schedule name, at most 40 characters, unique within the account. On update, omitting it keeps the current name.

Maximum string length: 40
name
string | null

Legacy name field, used on create only when schedule_name is empty. Ignored on update.

Maximum string length: 40
description
string | null

Schedule description, at most 500 characters. On update, omitting it keeps the current text and an empty string clears it.

Maximum string length: 500
team_id
integer<int64> | null

ID of the owning team; obtain it from POST /team/list. On create, omitting it leaves the schedule without a team (0); on update, omitting it keeps the current team.

time_zone
string

IANA time zone in which the schedule's wall-clock rules are evaluated, for example Asia/Shanghai or UTC; abbreviations such as EST and Etc/GMT±N are rejected. Set on create (default: evaluated in Asia/Shanghai); immutable afterwards — on update send nothing or the current value. On preview it sets the evaluation time zone.

layers
object[]

Rotation layers. Required in practice: on update the list replaces all existing layers, so omitting it deletes every layer. At most 1000 items per request; split larger sets into several calls.

Maximum array length: 1000
notify
object | null

Shift notification configuration. On update, omitting it keeps the current configuration; a sent object replaces it entirely.

start
integer<int64>

Preview window start, 10-digit Unix seconds. Required for /schedule/preview; ignored by create and update.

end
integer<int64>

Preview window end, 10-digit Unix seconds, after start and at most 45 days later. Required for /schedule/preview; ignored by create and update.

disabled
enum<integer> | null

Create only: 0 = enabled (default), 1 = disabled. Ignored on update — use status instead.

Available options:
0,
1,
null
status
enum<integer> | null

0 = enabled, 1 = disabled. On update, omitting it keeps the current state. On create it takes precedence over disabled.

Available options:
0,
1,
null

Response

Success

Success response envelope. On every 2xx response, request_id identifies the call (also mirrored in the Flashcat-Request-Id header) and data holds the endpoint-specific payload. Failure responses use a different shape — see ErrorResponse.

request_id
string
required

Unique ID for this request. Mirrored in the Flashcat-Request-Id response header. Include it when reporting issues.

Example:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

Schedule ID response returned after create.