Paid developer API reference

Allowed values

• Omitted: accepted (latest behavior).
• If present, must be exactly "2026-04-01" (PUBLIC_SCHEDULE_API_VERSION).
• Any other string is rejected (TYPE_ERROR).

Behavior

• Compared after trim-equivalent handling in sanitizeApiVersion.

Typical errors

• TYPE_ERRORUnsupported apiVersion value.

Allowed values

• Wire format is a single string. The API does NOT publish a closed enum of every allowed string in the schema: the server validates dynamically.
• Validation matches `isValidIanaTimeZone` in the codebase: Luxon `DateTime.now().setZone(zone).isValid` must be true.
• Use canonical IANA Time Zone Database identifiers, e.g. `Asia/Tokyo`, `America/New_York`, `Europe/Berlin`, `UTC`. The valid set is whatever IANA zones Luxon accepts for the deployed runtime, not a manually curated API enum.
• Do not rely on timezone abbreviations alone (`EST`, `JST`, `GMT`, etc.) — they are not stable IANA zone IDs and may be rejected.
• For reference lists of zone names, see the IANA tz distribution (https://www.iana.org/time-zones) or your platform’s timezone API.

Behavior

• Used with schedule dates and slot times in downstream normalization.
• If you need a fixed list in your client, derive it from the same rules (IANA IDs) rather than expecting a server-side enum in the JSON schema.

Typical errors

• INVALID_TIME_ZONEMissing, empty, or not a valid IANA zone.

Allowed values

• Must match /^\d{4}-\d{2}-\d{2}$/ (trimmed).
• Must be real calendar dates; the inclusive range must produce at least one day via enumerateDates.
• The number of days in range must not exceed maxScheduleDays (paid API typically up to 14 days for two-week planning; exact cap = tenant entitlements).

Behavior

• scheduleStartDate must be on or before scheduleEndDate.

Typical errors

• INVALID_DATE_RANGEBad format, invalid dates, or empty range.
• SCHEDULE_SPAN_TOO_LONGMore than maxScheduleDays days.

Allowed values

• Non-empty strings (trimmed) interpreted by the same slot enumeration as the UI (`enumerateSlotsByGranularity`).
• The pair must generate at least one slot; otherwise validation fails.

Behavior

• Together with slotGranularityMinutes, defines slotId values used in cellKey construction.

Typical errors

• INVALID_TIME_RANGEMissing values or zero slots generated for the range.

Allowed values

• Must be exactly 60 or 15 (not a string).
• Must also appear in allowedGranularities for the request. On the paid API both 60 and 15 are typically enabled; if 15 is disabled for your tenant, INVALID_GRANULARITY is returned.

Behavior

• Defines slot count together with the time range.

Typical errors

• INVALID_GRANULARITYNot 60/15, or not allowed for the plan.

Allowed values

• Must be a plain JSON object (not an array).
• Each key must be a cellKey in the expected grid for (dates × slotIds). Unknown keys → UNKNOWN_CELL_KEY.
• Each value must be a JSON number, integer, between 0 and 15 inclusive.
• Omitted cells are treated as 0 requirement where not specified (only cells with need ≥ 1 participate in SHORTFALL checks).

Behavior

• Keys are compared after trim via sanitizeCellKey.

Typical errors

• INVALID_REQUIREMENTSNot an object, or invalid numeric value for a key.
• UNKNOWN_CELL_KEYKey not in the computed date × slot grid.

Allowed values

• Length between 1 and maxStaffPerSchedule (default 500 for POST /v1/schedule; separate from the roster cap for POST /v1/staff).
• Each element must be a plain object with allowed keys only: staffId, displayName, availableCells (strict mode).
• staffId and displayName must survive sanitization (see Sanitization section).
• staffId must be unique across the array (DUPLICATE_STAFF_ID).

Behavior

• Order is preserved for availability counting.

Typical errors

• INVALID_STAFFEmpty array, too many rows, bad object, or failed sanitization.
• UNKNOWN_FIELDExtra key on a staff object in strict mode.
• DUPLICATE_STAFF_IDSame staffId twice.

Allowed values

• If omitted: the staff member is treated as available on all cells in the grid (implementation uses a null “all cells” set).
• If present: must be a JSON array of strings; each non-empty string must be a cellKey in the expected grid.
• Empty strings in the array are invalid (INVALID_AVAILABLE_CELL).

SHORTFALL check

• For every cell where required count ≥ 1, the number of staff who count as available for that cell must be ≥ required count, or SHORTFALL_CELLS.

Typical errors

• INVALID_AVAILABLE_CELLUnknown cell key or empty entry.
• SHORTFALL_CELLSNot enough staff cover required headcount for a cell.

What the API stores on the parent row

• The public API accepts only ROOT_KEYS at the top level and STAFF_KEYS on each staff object. Do not send laborLawJurisdiction, usLaborStateCode, laborModelVersion, or paidOptimization.
• On submit, the server sets the parent SCHEDULE_CONDITION from shared defaults: paidOptimization matches DEFAULT_PAID_OPTIMIZATION — laborLawCompliance false; balanceStaffLoad, honorShiftWishes, and preferConsecutiveShifts true (see schedule-defaults-shared.ts and build-schedule-transact-items.ts). laborLawJurisdiction JP, usLaborStateCode GENERIC, laborModelVersion v1.
• Statutory-style labor constraints in the optimizer require both parent and per-staff labor compliance flags to be on; this path leaves them off, so do not expect statutory caps to apply from this JSON alone.
• The labor model is an approximation for scheduling, not legal advice. Catalog: optimizer/config/labor_models.json.

Docs

• Full detail: docs/data-and-api/PUBLIC_API_SCHEDULE_REQUEST_BODY.md §2.1.1 and §3.1.

If you send disallowed keys

• UNKNOWN_FIELDStrict mode rejects unknown root or staff properties.