Record a coaching session

POST /api/v1/enrollments/{enrollmentId}/coaching-sessions

Records one coaching session on one enrollment, with its notes, decisions and commitments. At most one commitment may be promoted to the member's next action; the promotion replaces the current one. Everything is append-only: nothing recorded here is ever updated or deleted.

Authorization

Organization role

Business authorization

A platform-wide role grants nothing here. An enrollment of another organization, or one outside the caller's scope, is refused without revealing whether it exists.

Path parameters

Request headers

Request body

{
  "heldAt": "2026-09-01T14:30:00.000Z",
  "entries": [
    {
      "kind": "note",
      "visibility": "coach_only",
      "body": "Still hesitating between industrial SMEs and consultancies."
    },
    {
      "kind": "decision",
      "visibility": "shared_with_member",
      "body": "Focus on industrial SMEs until the end of the month."
    },
    {
      "kind": "commitment",
      "visibility": "shared_with_member",
      "body": "Build a list of 50 qualified industrial SMEs",
      "ownerType": "member",
      "dueAt": "2026-09-08T21:59:00.000Z",
      "promote": true
    }
  ]
}

Example

curl -X POST "$COHORTE_API_BASE_URL/api/v1/enrollments/ENROLLMENT_ID/coaching-sessions" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: coaching-session-2026-09-01" \
  -H 'Content-Type: application/json' \
  -d '{"heldAt":"2026-09-01T14:30:00.000Z","entries":[{"kind":"note","visibility":"coach_only","body":"Short debrief."}]}'

Response

• 201 Created — the session and its entries were recorded.
• 200 OK — the same Idempotency-Key replayed the original recording.
• 400 Bad Request — missing Idempotency-Key, invalid JSON, invalid entry, a past deadline, two promoted commitments, an inactive enrollment, or a blocker escalation holding the current action.
• 401 Unauthorized — the key is missing, invalid, or no longer attached to a member.
• 403 Forbidden — the bearer cannot document this enrollment.
• 404 Not Found — the enrollment is unknown or belongs to another organization.
• 409 Conflict — the current action changed while the session was being recorded.

Response fields

Example response

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "9f2c0a1e-0000-4000-8000-000000000000",
    "enrollmentId": "4af4cd8d-0000-4000-8000-000000000000",
    "heldAt": "2026-09-01T14:30:00.000Z",
    "recordedBy": "1b7d2f30-0000-4000-8000-000000000000",
    "recordedByName": "Karim Haddad",
    "recordedAt": "2026-09-01T14:32:00.000Z",
    "promotedNextActionId": "6d41ab55-0000-4000-8000-000000000000",
    "entries": [
      {
        "id": "3ac91b70-0000-4000-8000-000000000000",
        "kind": "commitment",
        "visibility": "shared_with_member",
        "body": "Build a list of 50 qualified industrial SMEs",
        "ownerType": "member",
        "ownerUserId": null,
        "dueAt": "2026-09-08T21:59:00.000Z",
        "promotedNextActionId": "6d41ab55-0000-4000-8000-000000000000",
        "supersedesEntryId": null,
        "addedAt": "2026-09-01T14:32:00.000Z"
      }
    ]
  },
  "correlationId": "0f6b1d92-0000-4000-8000-000000000000"
}

Notes

• Retrying with the same Idempotency-Key returns the original session and creates no second entry, audit record or event.
• The session, its entries and the promoted next action are written in one transaction: if the promotion is refused, nothing is recorded.
• Promotion replaces the member's current next action. When that action belongs to a blocker escalation, the whole request is refused with 400; record the session again without a promotion.
• The mutation emits coaching.session_recorded, and coaching.commitment_promoted when a commitment was promoted. No email or notification is sent by this endpoint.

Related

• List coaching sessions
• Get a coaching session
• Record live attendance

Scheduling retry contract

Keep one idempotency key for one normalized intention. Current authorization is checked again on retry. A different payload or resource with that key, or an older key whose intention cannot be verified, returns 409 conflict without another mutation. Inspect the original outcome before creating a new command. Identical retries do not resend notifications.