Program folders

Program folders group program templates in the template library. Each folder belongs to one studio and one program type, and carries a name, a colour and a sort order.


Source	`backend/apps/core-api/src/modules/program-folders/`
Lane	Web gateway only
Base path	`/v1/web/program-folders`
Guards	Service auth plus web user context. No `requireRole` guard, so every studio role can call it.

This module is smaller than the usual five-file pattern. It has two files: program-folders.routes.ts, which holds the handlers and an inline createService(prisma) that talks to Prisma directly, and program-folders.schema.ts with the Zod schemas.

The `ProgramFolder` row

Field	Type	Notes
`id`	string	cuid
`studioId`	string	Set from `req.auth.studioId`, never from the body
`type`	`TRAINING`, `NUTRITION` or `COMBINED`	The Prisma `ProgramType` enum. Set on create and not editable afterwards
`name`	string
`color`	string	Defaults to `#4f46e5`
`order`	integer	Defaults to `0`
`createdAt`	datetime
`updatedAt`	datetime

Endpoints

`GET /v1/web/program-folders`

Lists the studio’s folders. Auth: web lane, any role.

string

One of TRAINING, NUTRITION, COMBINED. Omit to return folders of every type.

Folders are ordered by order ascending, then createdAt ascending. There is no pagination. data is the array itself. Response:

{
  "ok": true,
  "data": [
    {
      "id": "cmf4p1q2r0001qz8h3s4t5u6v",
      "studioId": "cmstudio0001qz8h7w8x9y0z",
      "type": "TRAINING",
      "name": "Hypertrophy",
      "color": "#4f46e5",
      "order": 0,
      "createdAt": "2026-09-12T09:00:00.000Z",
      "updatedAt": "2026-09-12T09:00:00.000Z"
    },
    {
      "id": "cmf4p2a3b0002qz8h4c5d6e7f",
      "studioId": "cmstudio0001qz8h7w8x9y0z",
      "type": "TRAINING",
      "name": "Beginners",
      "color": "#16a34a",
      "order": 1,
      "createdAt": "2026-09-14T11:30:00.000Z",
      "updatedAt": "2026-09-20T08:15:00.000Z"
    }
  ]
}

Errors: UNAUTHORIZED with no studio context. VALIDATION (422) for an unknown type.

`POST /v1/web/program-folders`

Creates a folder. Returns 201. Auth: web lane, any role.

string

required

One of TRAINING, NUTRITION, COMBINED.

string

required

Folder name. Minimum length 1. There is no uniqueness check, so two folders can share a name.

string

Any string. Not validated as a colour. Falls back to the column default #4f46e5 when omitted.

integer

Sort position. Coerced with z.coerce.number().int(). Falls back to 0 when omitted.

Response: the created ProgramFolder row.

{
  "ok": true,
  "data": {
    "id": "cmf4p1q2r0001qz8h3s4t5u6v",
    "studioId": "cmstudio0001qz8h7w8x9y0z",
    "type": "NUTRITION",
    "name": "Cutting",
    "color": "#f59e0b",
    "order": 2,
    "createdAt": "2026-10-06T09:00:00.000Z",
    "updatedAt": "2026-10-06T09:00:00.000Z"
  }
}

Errors: VALIDATION for a bad body. UNAUTHORIZED with no studio context.

`PATCH /v1/web/program-folders/:id`

Renames, recolours or reorders a folder. Only the fields sent are written. type cannot be changed. Auth: web lane, any role.

string

required

The folder id.

string

Minimum length 1.

string

Any string.

integer

Sort position.

The service loads the folder scoped to the studio first, then updates it. Response: the updated ProgramFolder row, same shape as the create response. Errors: NOT_FOUND (folder not found) when the id does not exist or belongs to another studio. VALIDATION for a bad body.

`DELETE /v1/web/program-folders/:id`

Deletes a folder. Returns 204 with no body. Auth: web lane, any role.

string

required

The folder id.

Templates inside the folder are kept. The ProgramTemplate.folderId relation is declared with onDelete: SetNull, so those templates become unfiled. Errors: NOT_FOUND (folder not found).

API basics

Trainees

Plans and libraries

Tracking

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

Program folders

The `ProgramFolder` row

Endpoints

`GET /v1/web/program-folders`

`POST /v1/web/program-folders`

`PATCH /v1/web/program-folders/:id`

`DELETE /v1/web/program-folders/:id`

​The ProgramFolder row

​Endpoints

​GET /v1/web/program-folders

​POST /v1/web/program-folders

​PATCH /v1/web/program-folders/:id

​DELETE /v1/web/program-folders/:id

The `ProgramFolder` row

Endpoints

`GET /v1/web/program-folders`

`POST /v1/web/program-folders`

`PATCH /v1/web/program-folders/:id`

`DELETE /v1/web/program-folders/:id`