Teams API

The Teams module manages organizational units (schools, campuses, departments) for multi-tenancy.

Model

{
  "id": "uuid",
  "name": "Campus A",
  "code": "CAMPUS-A",
  "description": "Main campus",
  "parent_id": "root-team-uuid",
  "parent": {...},
  "children": [...],
  "level": 1,
  "path": "/root-uuid/campus-a-uuid/",
  "created_at": "2024-01-01T00:00:00Z"
}

Hierarchy

Teams form a hierarchical structure:

Root Organization (Level 0)
├── Campus A (Level 1)
│   ├── Primary School (Level 2)
│   └── Secondary School (Level 2)
└── Campus B (Level 1)

Endpoints

List Teams (Public)

Endpoint: POST /api/teams/list-public

Returns teams accessible to the authenticated user.

List Teams (Admin)

Endpoint: POST /api/teams/list

!!! warning “Admin Only” Full team management requires admin role.

Get Team by ID

Endpoint: GET /api/teams/:id

Create Team

Endpoint: POST /api/teams

Request:

{
  "name": "New Campus",
  "code": "CAMPUS-C",
  "description": "New campus location",
  "parent_id": "root-team-uuid"
}

Update Team

Endpoint: PUT /api/teams/:id

Delete Team

Endpoint: DELETE /api/teams/:id

!!! danger “Caution” Deleting a team affects all child teams and associated data.

User-Team Assignment

Assign Users to Team

Endpoint: PUT /api/teams/:id/assign

Request:

{
  "user_ids": ["user-uuid-1", "user-uuid-2"]
}

Remove Users from Team

Endpoint: PUT /api/teams/:id/remove

Data Isolation

All records include a team_id field. Queries automatically filter by:

Current team (from X-Team-ID header)
Child teams of current team

See Multi-tenancy for details.