---
title: "Save the structured agenda by session number (MED-1086 / E1.3m)"
method: POST
path: "/cohorts/{cohortId}/sessions/by-number/{sessionNumber}/agenda"
tags: ["Session Agenda Authoring"]
---

# Save the structured agenda by session number (MED-1086 / E1.3m)

`POST /cohorts/{cohortId}/sessions/by-number/{sessionNumber}/agenda`

## Request

- Base URL: `https://api.production.yourmedley.com`
- URL: `https://api.production.yourmedley.com/cohorts/{cohortId}/sessions/by-number/{sessionNumber}/agenda`
- Auth: none declared

Session-number-addressed full-replace save. A true upsert — a CM can
author and save a brand-new session number before groups exist. Same
payload and persistence as the sessionId POST.

## Path parameters

- `cohortId` string, uuid, required
- `sessionNumber` integer, required

## Request body

- SessionAgendaUpsertRequest
  - `description` string, nullable, required
  - `sections` SessionAgendaSection[], required
    - `id` string, uuid: Present on existing rows being kept on save; absent on new ones.
    - `section_name` string, nullable
    - `duration_minutes` integer, nullable: MED-1224 — section duration in whole minutes. Minimum valid value is 1; 0 and negatives are rejected. Nullable so an in-progress section with no duration yet can still be saved (AC-MC3).
    - `sort_order` integer, required: 1-based position in the agenda list.
    - `participant_prompt` string, nullable: MED-980 (E1.3e / AC-PP). Rich-text instructions shown to participants in-session, stored as sanitized HTML. Optional. Rendering to participants is E3.3a.
    - `show_commitment_field` boolean: MED-980 (E1.3e / AC-SCF). When true, the in-session participant view (E3.3a) surfaces the commitment-entry field in this section. UI gates the toggle on the cohort's commitment_tracking_enabled; the column persists regardless.
    - `show_last_session_commitment` boolean: MED-980 (E1.3e / AC-SLC). When true, the in-session participant view (E3.3a) displays the participant's prior-session commitment in this section. UI gates the toggle on the cohort's commitment_tracking_enabled.
    - `visuals` SessionAgendaVisual[], required
      - `slide_page` integer, required: 1-based page number in the uploaded slide deck PDF.
      - `sort_order` integer, required: 1-based display order within the section.
    - `leader_prompts` SessionAgendaLeaderPrompt[], required
      - `id` string, uuid: Present on existing rows being kept on save; absent on new ones.
      - `intro_text` string, nullable: Short single-line context above the discussion prompt.
      - `discussion_prompt` string, nullable: Rich-text HTML serialization (bold, italic, underline, bullet list).
      - `sort_order` integer, required: 1-based position in the section's prompt list (creation order).
  - `participant_pre_session_work` SessionAgendaPreSessionWork, required: MED-981 (E1.3f). Participant Pre-Session Work panel — configures what participants complete before the session. Pre-session page rendering is E3.1c (NOT this story).
    - `commitment_review_enabled` boolean, required: AC-CR1/CR3. When TRUE, the pre-session page (E3.1c) will surface the participant's prior-session commitment review. UI gates the toggle on cohort_commitment_tracking_enabled — hidden when off.
    - `reading_tasks` string, nullable, required: AC-RT1/RT2. Reading / Tasks rich-text (bold, italic, underline, bullet list). Sanitized server-side on write.
    - `reflection_prompts` SessionAgendaReflectionPrompt[], required
      - `id` string, uuid: Present on existing rows being kept on save; absent on new ones.
      - `prompt_text` string, nullable: Plain text — NOT rich text per the spec.
      - `sort_order` integer, required

## Response `200`

Saved; returns the canonical post-save bundle.

- object
  - `success` boolean
  - `data` SessionAgendaResponse: Full agenda bundle for a session's (cohort, modality, session_number) scope.
    - `cohort_id` string, uuid
    - `modality` 'group_coaching'
    - `session_number` integer
    - `topic` string, nullable: MED-1091 (E1.3n / AC5). Resolved session-number topic for the editor's "Session Topic" field: COALESCE(session_number_config.topic, the legacy cohort_session_topics topic name). The same value the View-by-Session header shows — deliberately NOT sessions.title. Null when no topic is set (editor shows the "Add session topic" empty affordance, AC7).
    - `description` string, nullable: Multi-line plain-text session description (AC-SD2).
    - `cohort_commitment_tracking_enabled` boolean: MED-980 (E1.3e / AC-SCF2, AC-SLC2) + MED-981 (E1.3f / AC-CR2). commitment_tracking_enabled from the cohort's group_coaching modality (MED-1069 / E1.10c, v230 — relocated from the cohort column). The editor uses this to gate BOTH the per-section commitment toggles (e1.3e) and the Enable Commitment Review toggle on the pre-session work panel (e1.3f) — hidden entirely when false.
    - `session_duration_minutes` integer, nullable: MED-1074 (E1.3j / AC6). The configured session length for this cohort's modality (modalities.session_duration_minutes, set at cohort setup). The editor renders the agenda's running duration total alongside this and warns (advisory, non-blocking) when the total exceeds it. Null when the modality has no configured length; the editor then shows the total without the comparison and suppresses the warning (AC7).
    - `marked_complete` boolean: MED-1232 (E1.3 / AC6, AC8). The persisted one-way "Mark Complete" release state. True once the CM has released this scope's content to the cohort; the editor then renders the completed-state indicator instead of the Mark Complete button. The CM can still edit + Save and it stays complete (no revert / no reopen).
    - `completed_at` string, date-time, nullable: ISO timestamp of first release, or null while in progress.
    - `sections` SessionAgendaSection[]
      - `id` string, uuid: Present on existing rows being kept on save; absent on new ones.
      - `section_name` string, nullable
      - `duration_minutes` integer, nullable: MED-1224 — section duration in whole minutes. Minimum valid value is 1; 0 and negatives are rejected. Nullable so an in-progress section with no duration yet can still be saved (AC-MC3).
      - `sort_order` integer, required: 1-based position in the agenda list.
      - `participant_prompt` string, nullable: MED-980 (E1.3e / AC-PP). Rich-text instructions shown to participants in-session, stored as sanitized HTML. Optional. Rendering to participants is E3.3a.
      - `show_commitment_field` boolean: MED-980 (E1.3e / AC-SCF). When true, the in-session participant view (E3.3a) surfaces the commitment-entry field in this section. UI gates the toggle on the cohort's commitment_tracking_enabled; the column persists regardless.
      - `show_last_session_commitment` boolean: MED-980 (E1.3e / AC-SLC). When true, the in-session participant view (E3.3a) displays the participant's prior-session commitment in this section. UI gates the toggle on the cohort's commitment_tracking_enabled.
      - `visuals` SessionAgendaVisual[], required
        - `slide_page` integer, required: 1-based page number in the uploaded slide deck PDF.
        - `sort_order` integer, required: 1-based display order within the section.
      - `leader_prompts` SessionAgendaLeaderPrompt[], required
        - `id` string, uuid: Present on existing rows being kept on save; absent on new ones.
        - `intro_text` string, nullable: Short single-line context above the discussion prompt.
        - `discussion_prompt` string, nullable: Rich-text HTML serialization (bold, italic, underline, bullet list).
        - `sort_order` integer, required: 1-based position in the section's prompt list (creation order).
    - `participant_pre_session_work` SessionAgendaPreSessionWork: MED-981 (E1.3f). Participant Pre-Session Work panel — configures what participants complete before the session. Pre-session page rendering is E3.1c (NOT this story).
      - `commitment_review_enabled` boolean, required: AC-CR1/CR3. When TRUE, the pre-session page (E3.1c) will surface the participant's prior-session commitment review. UI gates the toggle on cohort_commitment_tracking_enabled — hidden when off.
      - `reading_tasks` string, nullable, required: AC-RT1/RT2. Reading / Tasks rich-text (bold, italic, underline, bullet list). Sanitized server-side on write.
      - `reflection_prompts` SessionAgendaReflectionPrompt[], required
        - `id` string, uuid: Present on existing rows being kept on save; absent on new ones.
        - `prompt_text` string, nullable: Plain text — NOT rich text per the spec.
        - `sort_order` integer, required

## Other responses

- `401`: Unauthorized
- `404`: Cohort has no active group_coaching modality, or sessionNumber is out of range.
- `422`: Validation failed (malformed payload).

---

[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)