Special Schedules Via API

| Overview

Special Schedules via API, also known as exception-based schedules, is a new feature introduced in the 75F ecosystem that can be applied at the building or zone level.

Perfect for events or override scenarios, this feature gives facility teams more flexibility and automation.

Users Can:

• Create, Update & Delete special schedules via API Define date, time, mode (occupied/unoccupied), and setpoints.

• Automate holiday/event HVAC adjustments or bulk changes. Integrate with corporate calendars, DR systems, and facility tools.

• Maintain validations, conflict checks, and audit logs for integrity.

The following are the advantages of the feature:

• Energy Use – Adjust HVAC only when needed.

• Seamless Integrations – Connect calendars and scheduling systems directly.

• Remote Control – Manage building operations in bulk, from anywhere.

• Compliance & Accuracy – All user limits, deadbands, and setbacks are enforced.

Facility Managers, Installers, and Support Teams can now easily handle exceptions without disrupting regular schedules.

| Sample Base URL

https://api.75f.io/v2/schedules/special

Authentication:

OAuth2 bearer token
Required scopes: schedules:read, schedules:write

| Endpoints

 Create Special Schedule

POST /v2/schedules/special

Request Body:

{
  "zoneId": "zone-123",
  "date": "2025-07-04",
  "startTime": "08:00",
  "endTime": "18:00",
  "mode": "occupied",
  "setpoints": {
    "cooling": 74,
    "heating": 68
  },
  "description": "Independence Day override"
}

Success Response:

{
  "status": "success",
  "scheduleId": "sched-456"
}

Error Responses:

Code

Message

400

"Special Schedule : Invalid time range"

409

"Special Schedule : Schedule already exists for this date and zone"

403

"Special Schedule : Unauthorized to modify zone schedules"

422

"Special Schedule : Missing required fields"

Update Special Schedule

PUT /v2/schedules/special/{scheduleId}

Request Body:

Same as creation, with modified fields.

Response:

{
  "status": "updated",
  "scheduleId": "sched-456"
}

Errors:

Code

Message

404

"Schedule not found"

400

"New times conflict with another schedule"

 Delete Special Schedule

DELETE /v2/schedules/special/{scheduleId}

Success:

{
  "status": "deleted"
}

Errors:

Code

Message

404

"Schedule not found"

403

"Unauthorized to delete this schedule"

| Validation Rules

Note: All special schedule validations with other schedules within the system should be treated the same.

| Special Schedule Validations

Validations used in special schedules have to be repeated even if the API is used to create the special schedule.

All validations related to overlaps, conflicts, and schedule consistency apply identically to special schedules as they do to other schedule types. Below are key validations:

Conflict & Time Validations

• Overlap with another Special Schedule:

  • If a zone or building already has a special schedule at a given time, a new one for the same duration should be rejected.

  • Error: 409 Conflict – "Conflicting special schedule exists"

• Invalid Time Range:

  • Start time cannot be after the end time.

  • Error: 400 Bad Request – "Invalid time range".

• Missing Fields or Invalid Data:

  • Required fields like date, startTime, endTime, or mode must be present.

  • Error: 422 Unprocessable Entity.

Consistency with Schedule Rules

• Same Validation Rules as Zone/Named Schedules:

  • Deadbands, setbacks, and user limits in special schedules are validated using the same engine as zone and named schedules.

  • These must respect site-level constraints (like min/max limits).

  • Schedule block validation must account for these ranges.

Hierarchy Inheritance:

• Special schedules may override regular ones, but should still inherit building-level constraints unless explicitly overridden.

Error Handling Summary

| Validation Rules like Zone and Named Schedules

Time Range Validations

• Each schedule block must have:

  • A valid start time and end time.

  • The start time must be before the end time.

• No two blocks in a single schedule should overlap.

• Total daily schedule blocks per zone or named schedule should not exceed system-defined limits (e.g., max 10 blocks per day – based on implementation).

Day Coverage Validations

• Valid days of the week must be selected (e.g., Monday to Sunday).

• Multiple blocks can exist per day, but must comply with overlap and range validations.

• Holiday or Exception Handling should fall under special schedules and not be mixed into regular weekly schedules.

| Temperature Settings Validations

Each schedule block can define:

• Desired Heating Setpoint (e.g., 68°F)
• Desired Cooling Setpoint (e.g., 74°F)

These are validated against:

User Limits (Usually defined at the zone or building level, and now part of the schedule).

Deadband

• A minimum gap between heating and cooling setpoints.

Example: If heating is 70°F and deadband is 2°F, cooling must be ≥72°F.

Invalid if: Cooling - Heating < Deadband.

Unoccupied Zone Setback

• Applied when the zone is unoccupied.
• The schedule must define how setbacks apply in “unoccupied” blocks.

| Schedulable Parameters

Every schedule must contain the following 7 "schedulable" parameters, and they must pass validations:

| Bulk Operations Validations

When applying or reverting schedules in bulk:

• All target zones must be eligible to receive the schedule.
• Validations for each zone must pass (user limits, no conflicts).
• If even one zone fails, the operation should fail or give granular feedback per zone.

When API is scheduled - Compatibility Rules

During or post-migration:

• The system must validate if the schedules (old building or zone) have all 7 new parameters.
• If any parameter is missing, it must:
  • Pull values from pre-migration tuners.
  • Or fall back to building default limits for schedule validation.

Common Error Responses