Mentorships¶

Endpoints for managing coach-teacher mentorship relationships.

Base path: /api/mentorships

Authentication: All endpoints require a valid session and an organization context.

Endpoints¶

Method	Path	Min Role	Description
`GET`	`/api/mentorships`	`Teacher`	List mentorships
`POST`	`/api/mentorships`	`Coach`	Create a mentorship
`GET`	`/api/mentorships/:id`	`Teacher`	Get mentorship details
`PATCH`	`/api/mentorships/:id`	`Coach`	Update mentorship
`DELETE`	`/api/mentorships/:id`	`Manager`	End a mentorship

Data Model¶

A mentorship links one coach to one teacher within an organization. It has a lifecycle status and optional metadata.

Field	Type	Description
`id`	string	UUID
`organizationId`	string	Organization the mentorship belongs to
`coachId`	string	User CUID of the assigned coach
`teacherId`	string	User CUID of the assigned teacher
`status`	string	`pending`, `active`, `paused`, or `ended`
`title`	string \| null	Optional title
`description`	string \| null	Optional description
`notes`	string \| null	Internal notes (not shared with teacher)
`createdAt`	string	ISO 8601 timestamp
`updatedAt`	string	ISO 8601 timestamp

Enriched responses also include nested coach and teacher objects with profile data.

GET /api/mentorships¶

List mentorships visible to the caller.

Access rules:

Coach: only sees mentorships where they are the coach.
Teacher: only sees mentorships where they are the teacher.
Manager, OrganizationAdmin, PlatformAdmin: see all mentorships in the org (with optional filters).

Query parameters:

Parameter	Type	Description
`limit`	integer	Max records (default: `50`, max: `200`)
`offset`	integer	Records to skip (default: `0`)
`status`	string	Filter by status: `pending`, `active`, `paused`, or `ended`
`coachId`	string	Filter by coach ID (admin/manager only)
`teacherId`	string	Filter by teacher ID (admin/manager only)

Response 200:

{
  "data": [
    {
      "id": "mentorship-uuid",
      "organizationId": "org-uuid",
      "coachId": "coach-cuid",
      "teacherId": "teacher-cuid",
      "status": "active",
      "title": "Spring Coaching Program",
      "description": "Weekly 1:1 sessions",
      "notes": null,
      "createdAt": "2025-02-01T00:00:00.000Z",
      "updatedAt": "2025-02-01T00:00:00.000Z",
      "coach": {
        "id": "coach-cuid",
        "email": "coach@example.com",
        "firstName": "Alice",
        "lastName": "Johnson",
        "avatarUrl": null
      },
      "teacher": {
        "id": "teacher-cuid",
        "email": "teacher@example.com",
        "firstName": "Bob",
        "lastName": "Williams",
        "avatarUrl": null
      }
    }
  ],
  "meta": {
    "total_count": 8
  }
}

Error responses:

Code	Condition
`400`	No organization context

POST /api/mentorships¶

Create a new mentorship between a coach and a teacher in an organization. Only one mentorship may exist per coach-teacher pair per organization.

Min role: Coach

Access rules:

Coach can only create mentorships where they are the coach (coachId must equal the caller's ID).
Non-PlatformAdmin callers cannot create mentorships in a different org than their active org.

Request body:

{
  "organizationId": "org-uuid",
  "coachId": "coach-cuid",
  "teacherId": "teacher-cuid",
  "title": "Spring Coaching Program",
  "description": "Weekly 1:1 sessions",
  "notes": "Initial notes"
}

Field	Type	Required	Constraints
`organizationId`	string	Yes	Must be a valid UUID
`coachId`	string	Yes	Must be an existing user; must have `Coach` role in the org
`teacherId`	string	Yes	Must be an existing user; must have `Teacher` role in the org
`title`	string	No	Maximum 255 characters
`description`	string	No	Maximum 2000 characters
`notes`	string	No	Maximum 1000 characters

Response 201:

{
  "data": {
    "id": "mentorship-uuid",
    "organizationId": "org-uuid",
    "coachId": "coach-cuid",
    "teacherId": "teacher-cuid",
    "status": "pending",
    "title": "Spring Coaching Program",
    "description": "Weekly 1:1 sessions",
    "notes": "Initial notes",
    "createdAt": "2025-04-01T12:00:00.000Z",
    "updatedAt": "2025-04-01T12:00:00.000Z"
  }
}

Error responses:

Code	Condition
`400`	No organization context
`403`	`Coach` attempting to create a mentorship for another coach; or org mismatch
`409`	A mentorship between this coach and teacher already exists in this org
`422`	`coachId` is not a `Coach` in the org; or `teacherId` is not a `Teacher` in the org

GET /api/mentorships/:id¶

Get full details of a single mentorship.

Access rules:

Coach: can only view their own mentorships.
Teacher: can only view their own mentorships.
Manager, OrganizationAdmin, PlatformAdmin: can view any mentorship in the org.

Path parameters:

Parameter	Type	Description
`id`	string	Mentorship UUID

Response 200:

{
  "data": {
    "id": "mentorship-uuid",
    "organizationId": "org-uuid",
    "coachId": "coach-cuid",
    "teacherId": "teacher-cuid",
    "status": "active",
    "title": "Spring Coaching Program",
    "description": "Weekly 1:1 sessions",
    "notes": null,
    "createdAt": "2025-02-01T00:00:00.000Z",
    "updatedAt": "2025-02-01T00:00:00.000Z",
    "coach": {
      "id": "coach-cuid",
      "email": "coach@example.com",
      "firstName": "Alice",
      "lastName": "Johnson",
      "avatarUrl": null
    },
    "teacher": {
      "id": "teacher-cuid",
      "email": "teacher@example.com",
      "firstName": "Bob",
      "lastName": "Williams",
      "avatarUrl": null
    }
  }
}

Error responses:

Code	Condition
`403`	`Coach` or `Teacher` viewing a mentorship they are not part of
`404`	Mentorship not found

PATCH /api/mentorships/:id¶

Update a mentorship's metadata or status.

Access rules:

Coach can update title, description, and notes for their own mentorships only.
Coach cannot change status.
Manager, OrganizationAdmin, PlatformAdmin can update all fields.

Path parameters:

Parameter	Type	Description
`id`	string	Mentorship UUID

Request body (all fields optional):

{
  "status": "active",
  "title": "Updated Title",
  "description": "Updated description",
  "notes": "Updated notes"
}

Field	Type	Constraints
`status`	string	`pending`, `active`, `paused`, or `ended`; not allowed for `Coach` callers
`title`	string	Maximum 255 characters
`description`	string	Maximum 2000 characters
`notes`	string	Maximum 1000 characters

Response 200:

{
  "data": {
    "id": "mentorship-uuid",
    "status": "active",
    ...
  }
}

Error responses:

Code	Condition
`403`	`Coach` attempting to update another coach's mentorship, or attempting to change `status`
`404`	Mentorship not found

DELETE /api/mentorships/:id¶

End a mentorship. Sets its status to ended and cancels all scheduled or confirmed sessions.

Min role: Manager

Path parameters:

Parameter	Type	Description
`id`	string	Mentorship UUID

Response 200:

{
  "data": {
    "id": "mentorship-uuid",
    "status": "ended",
    ...
  }
}

Error responses:

Code	Condition
`404`	Mentorship not found