---
title: "Update modality settings (coaching sub-type, AI features, commitment tracking)"
method: PATCH
path: "/cohorts/{id}/modalities/{modalityId}/settings"
tags: ["Cohorts"]
---

# Update modality settings (coaching sub-type, AI features, commitment tracking)

`PATCH /cohorts/{id}/modalities/{modalityId}/settings`

## Request

- Base URL: `https://api.production.yourmedley.com`
- URL: `https://api.production.yourmedley.com/cohorts/{id}/modalities/{modalityId}/settings`
- Auth: HTTP bearer

MED-848 — Non-destructive update of a single modality's coaching sub-type,
AI features toggle, Live Session Delivery gate, and (MED-1069) Commitment
Tracking toggle. Used by the Edit Cohort flow.

Editability rules:
- `ai_features_enabled` is editable any time post-creation (AC8)
- `coaching_sub_type` is editable only until the modality is locked by
  either of the following independent conditions (returns 400 once locked):
    1. **MED-848 AC9** — `invites_sent=true` (session prep / announcement
       emails have already gone out for this modality).
    2. **MED-955 AC1/3/5** — any session in the cohort has a designated
       `session_leader_id` (Coach Led / Peer Led leader has been assigned).
       Reported as: _"Modality type cannot be changed after session leaders have been assigned."_
- `coaching_sub_type` is only valid for `modality_type='group_coaching'`. Returns 400 otherwise.

Gated by the `live_session_delivery` feature flag (MED-886). When the
flag is off the endpoint returns 404.

## Path parameters

- `id` string, uuid, required
- `modalityId` string, uuid, required

## Request body

- object
  - `coaching_sub_type` 'coach_led' | 'peer_led', nullable: Group coaching sub-type. Only valid when the modality is group_coaching. Locked once `invites_sent=true` (MED-848 AC9) OR once any session in the cohort has a designated `session_leader_id` (MED-955 AC1/3/5).
  - `ai_features_enabled` boolean: Whether AI-powered facilitation features are enabled for this modality.
  - `live_session_delivery_enabled` boolean: MED-948 (E1.10a) — per-modality Live Session Delivery in SGOS gate. When set to false, `ai_features_enabled` is reset to false server-side (AC8) so no stale "enabled-but-hidden" state persists. Distinct from the system-level `live_session_delivery` feature flag (MED-886).
  - `commitment_tracking_enabled` boolean: MED-1069 (E1.10c) — per-modality Commitment Tracking toggle (group_coaching only). Enables the participant "Reflect on Prior Commitments" step and per-session commitment field for the cohort's group sessions. INDEPENDENT of `live_session_delivery_enabled` — it is NOT reset when that gate is turned off (unlike `ai_features_enabled`).

## Response `200`

Modality settings updated

## Other responses

- `400`: Validation failed, sub-type set on non-group_coaching modality, or sub-type locked. Two lock reasons map to distinct error messages: - _"Modality type cannot be changed after session leaders have been assigned."_ (MED-955) - _"Coaching sub-type is locked because session prep emails have already been sent for this modality"_ (MED-848 AC9)
- `401`: Unauthorized
- `404`: Cohort or modality not found, OR the `live_session_delivery` feature flag is off (MED-886)
- `422`: Request body validation error

---

[API](https://skmtc.dev/withmedley/apis/medley-api.md) - [All operations](https://skmtc.dev/withmedley/apis/medley-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withmedley/apis/medley-api/revisions/40aaac5ca6bd?raw)