# Teams API

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

## Model

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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](../../architecture/multi-tenancy.md) for details.