Coaches API

​

Mounting and auth

​

Roles

​

Owner protection

• Editing your own row is always allowed.
• The studio owner is found through the organization membership table: the member row with role owner for the studio’s externalOrgId. If the target row is the owner’s and the caller is someone else, the request fails with FORBIDDEN (“only the studio owner can change their own profile”).
• When the owner cannot be identified (no linked organization, or no owner member), only a caller with role OWNER may change a HEAD_COACH other than themselves. Others get FORBIDDEN (“cannot change another admin on this team”).

​

Related behaviour in the web lane

• For a caller with role OWNER, it upserts a HEAD_COACH row for that user, using the x-user-name and x-user-email headers.
• It updates lastActiveAt on the caller’s row, at most once every 5 minutes per coach. This feeds the “last activity” column on the team page.

​

The coach object

{
  "id": "cmf1bb0000000coach0000001",
  "studioId": "cmf1aa0000000studio000001",
  "externalUserId": "user_8f2c",
  "role": "SUB_COACH",
  "name": "Noa Cohen",
  "firstName": "Noa",
  "lastName": "Cohen",
  "roleTitle": "Nutrition coach",
  "permissionGroup": null,
  "permissions": {
    "trainees": "assigned",
    "plans": "useTemplates",
    "forms": "view",
    "content": "view",
    "subscriptions": "assign",
    "discount": { "enabled": false, "maxPercent": 5 }
  },
  "lastActiveAt": "2026-10-06T14:20:00.000Z",
  "email": "noa@example.com",
  "phone": "0521234567",
  "healthScore": null,
  "active": true,
  "createdAt": "2026-08-12T09:00:00.000Z",
  "updatedAt": "2026-10-06T14:20:00.000Z"
}

​

Permissions blob

• A HEAD_COACH always holds everything, whatever is stored.
• A SUB_COACH with no stored blob, or a blob that fails the schema, also holds everything. Coaches created before the permission model keep studio-wide access until someone configures them on the team screen.
• A SUB_COACH with a valid blob holds what the blob says.
• A row with active: false grants nothing. The clients router answers such a caller with FORBIDDEN.

​

Endpoints

​

GET /v1/web/coaches

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "cmf1bb0000000coach0000001",
        "name": "Noa Cohen",
        "role": "SUB_COACH",
        "email": "noa@example.com",
        "active": true
      }
    ],
    "total": 4,
    "page": 1,
    "pageSize": 20
  },
  "requestId": "req_01"
}

​

POST /v1/web/coaches

1. Inserts the Coach row with name built from first and last name. When billing plan limits apply, the insert runs inside the studio’s seat lock (planLimits.withSeat), so the seat count and the insert cannot race.
2. Calls the team invite mailer with the studio id, email, name, job title and the inviting user’s id. The call is fire-and-forget: the response does not wait for it, and a failure is only logged (“team invitation: failed”).

• VALIDATION: body fails the schema.
• FORBIDDEN: “insufficient role”, or the plan has no free seat (details.reason is PLAN_LIMIT_SEATS, with limit, count and planId).
• CONFLICT: a Coach row with the same externalUserId already exists in the studio (Prisma P2002 on the studioId and externalUserId unique index).

​

GET /v1/web/coaches/:id

​

GET /v1/web/coaches/:id/impact

{ "ok": true, "data": { "openTasks": 7, "clients": 23 } }

• openTasks: InboxItem rows with status OPEN or SNOOZED whose coachIds include this coach.
• clients: trainees (with deletedAt null) that have a ClientCoach assignment to this coach.

​

PATCH /v1/web/coaches/:id

1. Loads the row and runs the owner protection check.
2. When active: true is sent for an inactive member, calls planLimits.assertCanAddCoach, because the member takes a seat again.
3. In one transaction, updates the Coach row. If the row has an externalUserId and the studio is linked to an organization, it also updates that user’s member row role to organizationRoleForStaff(permissionGroup, role). A member row with role owner is never changed.

• NOT_FOUND: “coach not found”.
• FORBIDDEN: “insufficient role”, “only the studio owner can change their own profile”, “cannot change another admin on this team”, or no free seat on reactivation (PLAN_LIMIT_SEATS).
• VALIDATION: body fails the schema.
• CONFLICT: a unique constraint failed.

​

DELETE /v1/web/coaches/:id

{
  "tasks": { "mode": "reassign", "coachIds": ["cmf1bb0000000coach0000002"] },
  "clients": { "mode": "reassign", "coachIds": ["cmf1bb0000000coach0000002", "cmf1bb0000000coach0000003"] }
}

1. Loads the row and runs the owner protection check.
2. Resolves the replacement ids for each reassign mode. Duplicates and the dismissed coach’s own id are removed. Every remaining id must be an active coach of the studio.
3. Loads the member’s open tasks (InboxItem with status OPEN or SNOOZED and this coach in coachIds) and assigned trainees, both oldest first.
4. Plans the changes (coaches.dismissal.ts):
   • Tasks. In each task’s coachIds, the dismissed coach is swapped for a replacement. Replacements rotate through the list in order (round-robin by task index). With discard, the coach is removed. A shared task keeps its other assignees. A task left with no assignee is discarded.
   • Trainees. The same swap on each trainee’s coach list. The primary coach (Client.coachId) is kept when still on the list. Otherwise the first remaining coach becomes primary, or null.
5. Applies everything in one transaction (applyDismissal, timeout 30 seconds):
   • Discarded tasks get status DISMISSED, resolvedAt set to now, and no assignees.
   • Reassigned tasks get the new coachIds and coachId.
   • The dismissed coach’s ClientCoach rows are deleted, the replacement rows are created, and Client.coachId is updated.
   • The coach is removed from task automations: TaskAutomation.assigneeCoachId, TaskAutomation.assigneeCoachIds and TaskAutomationTask.assigneeCoachIds.
   • The Coach row is set to active: false.
   • If the row has an externalUserId and the studio is linked to an organization, the user’s member row is deleted, unless its role is owner.

{
  "ok": true,
  "data": {
    "coach": {
      "id": "cmf1bb0000000coach0000001",
      "name": "Noa Cohen",
      "active": false
    },
    "tasksReassigned": 5,
    "tasksDiscarded": 2,
    "clientsUpdated": 23
  }
}

• NOT_FOUND: “coach not found”.
• FORBIDDEN: “insufficient role”, “only the studio owner can change their own profile”, “cannot change another admin on this team”.
• VALIDATION: body fails the schema. “select at least one other team member” when a reassign list is empty after removing the dismissed coach. “unknown team member selected” when an id is not an active coach of the studio.

​

Common errors