Scheduling Rule Sets

Configure deterministic scheduling rules that filter appointment slots before they reach the agent.

Scheduling rule sets define workspace-scoped configuration for the deterministic scheduling rules engine. Each rule set binds an agent kind and rule kind to a typed parameter block that controls how the engine filters appointment slots.

Rule sets are scoped to a workspace. The combination of agent kind and rule kind is unique per workspace - each workspace can have at most one rule set per (agent kind, rule kind) pair.

Endpoints

All endpoints are scoped to a workspace: /v1/{workspace_id}/scheduling-rule-sets

Method	Path	Description
GET	/	List scheduling rule sets
GET	/{rule_set_id}	Get one scheduling rule set
POST	/	Create a scheduling rule set
PATCH	/{rule_set_id}	Partially update a scheduling rule set
DELETE	/{rule_set_id}	Delete a scheduling rule set

List Scheduling Rule Sets

GET /v1/{workspace_id}/scheduling-rule-sets

Returns a paginated list of scheduling rule sets for the workspace.

Query parameters:

Parameter	Type	Description
agent_kind	string (optional)	Filter by agent kind: tms, ketamine, or general
is_active	boolean (optional)	Filter by active status
limit	integer (optional)	Page size (default 50)
continuation_token	integer (optional)	Offset for pagination

Response: PaginatedResponse<SchedulingRuleSetResponse>

Permissions: Workspace.view

Get One Scheduling Rule Set

GET /v1/{workspace_id}/scheduling-rule-sets/{rule_set_id}

Returns a single scheduling rule set by ID.

Response: SchedulingRuleSetResponse

Permissions: Workspace.view

Errors:

• 404 - Rule set not found in this workspace

Create a Scheduling Rule Set

POST /v1/{workspace_id}/scheduling-rule-sets

Creates a new scheduling rule set. The rule_kind is determined by the discriminator field inside params.

Request body:

Field	Type	Required	Description
agent_kind	string	Yes	One of tms, ketamine, general
params	object	Yes	Per-rule-kind typed parameters (see Rule Kinds below)
is_active	boolean	No	Whether the rule is active (default true)

Response: SchedulingRuleSetResponse (HTTP 201)

Permissions: Workspace.update

Errors:

• 409 - A rule set already exists for this (agent kind, rule kind). Update the existing row or delete it first.

• 422 - Invalid request body or rule kind discriminator

Update a Scheduling Rule Set

PATCH /v1/{workspace_id}/scheduling-rule-sets/{rule_set_id}

Partially updates an existing rule set. Only params and is_active can be changed. agent_kind and rule_kind are immutable - to change either, create a new rule set and delete the old one.

When updating params, send the complete params object for the rule kind. Partial updates within params are not supported.

Request body:

Field	Type	Required	Description
params	object	No	Full replacement params for the rule kind
is_active	boolean	No	Whether the rule is active

At least one field must be provided.

Response: SchedulingRuleSetResponse

Permissions: Workspace.update

Errors:

• 404 - Rule set not found in this workspace

• 422 - Empty update body, or the params discriminator does not match the existing rule's kind

Delete a Scheduling Rule Set

DELETE /v1/{workspace_id}/scheduling-rule-sets/{rule_set_id}

Permanently deletes a scheduling rule set. The deletion is recorded in the audit log.

Response: HTTP 204 (no content)

Permissions: Workspace.update

Errors:

• 404 - Rule set not found in this workspace

Rule Set Model

Field	Type	Description
id	UUID	Unique identifier
workspace_id	UUID	Workspace this rule set belongs to
agent_kind	string	Agent kind: tms, ketamine, or general
rule_kind	string	Rule kind (see Rule Kinds below)
params	object	Per-rule-kind typed parameters
is_active	boolean	Whether this rule is active
created_by	UUID or null	Entity that created this rule set
created_at	datetime or null	Creation timestamp
updated_at	datetime or null	Last update timestamp

Rule Kinds

The params object uses a discriminated union keyed by rule_kind. Each rule kind has its own parameter shape.

clinic_open_hours

Defines clinic open hours by weekday. Days not present mean the clinic is closed that day.

Field	Type	Description
rule_kind	"clinic_open_hours"	Discriminator
timezone	string	Timezone identifier (e.g., America/New_York)
monday	object or null	{start, end} in HH:MM 24-hour format
tuesday	object or null	{start, end} in HH:MM 24-hour format
wednesday	object or null	{start, end} in HH:MM 24-hour format
thursday	object or null	{start, end} in HH:MM 24-hour format
friday	object or null	{start, end} in HH:MM 24-hour format
saturday	object or null	{start, end} in HH:MM 24-hour format
sunday	object or null	{start, end} in HH:MM 24-hour format

tms_mapping_release

Controls how long before a TMS mapping appointment its slot is released back to the pool.

Field	Type	Description
rule_kind	"tms_mapping_release"	Discriminator
reservation_window_hours	integer (0-720)	Hours before mapping appointment to release the slot
weekend_skip	boolean	Whether to skip weekends in the countdown (default true)

tms_session_grid

Restricts TMS session start times to fixed minute-of-hour boundaries so sessions run back-to-back without gaps.

Field	Type	Description
rule_kind	"tms_session_grid"	Discriminator
interval_minutes	integer (5-120)	Interval between session starts
boundary_minutes	array of integers	Allowed minute-of-hour values (0-59), at least one required

ketamine_block_overlap

Blocks follow-up appointments within a clinical safety window after a ketamine session.

Field	Type	Description
rule_kind	"ketamine_block_overlap"	Discriminator
window_days	integer (1-365)	Days after a ketamine session to block follow-up appointments

ninety_day_rolling

Caps appointments per patient within a rolling time window.

Field	Type	Description
rule_kind	"ninety_day_rolling"	Discriminator
days	integer (1-365)	Rolling window length in days

concurrent_start_block

Prevents two slots from starting at the same time within a scope. No additional parameters beyond the discriminator.

Field	Type	Description
rule_kind	"concurrent_start_block"	Discriminator

Example

Create a clinic open hours rule:

POST /v1/{workspace_id}/scheduling-rule-sets

{
  "agent_kind": "tms",
  "params": {
    "rule_kind": "clinic_open_hours",
    "timezone": "America/New_York",
    "monday": {"start": "08:00", "end": "17:00"},
    "tuesday": {"start": "08:00", "end": "17:00"},
    "wednesday": {"start": "08:00", "end": "17:00"},
    "thursday": {"start": "08:00", "end": "17:00"},
    "friday": {"start": "08:00", "end": "12:00"}
  },
  "is_active": true
}

Update params on an existing rule:

PATCH /v1/{workspace_id}/scheduling-rule-sets/{rule_set_id}

{
  "params": {
    "rule_kind": "clinic_open_hours",
    "timezone": "America/Chicago",
    "monday": {"start": "09:00", "end": "18:00"},
    "tuesday": {"start": "09:00", "end": "18:00"},
    "wednesday": {"start": "09:00", "end": "18:00"},
    "thursday": {"start": "09:00", "end": "18:00"},
    "friday": {"start": "09:00", "end": "14:00"}
  }
}

Disable a rule without deleting it:

PATCH /v1/{workspace_id}/scheduling-rule-sets/{rule_set_id}

{
  "is_active": false
}