# API Documentation

Base URL: `https://your-domain.com/api`
Auth: Bearer token (Laravel Sanctum). Obtain via `POST /login`, send as
`Authorization: Bearer {token}` on every subsequent request.

## Authentication

| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | `/login` | none | `{email, password}` → `{user, token}` |
| POST | `/logout` | token | Revokes the current token |
| POST | `/password/forgot` | none | `{email}` → sends reset link |

## Students

| Method | Endpoint | Description |
|---|---|---|
| GET | `/students` | List (filters: `class_arm_id`, `status`, `search`) |
| POST | `/students` | Create |
| GET | `/students/{id}` | Detail (class, scores, invoices, documents, guardians) |
| PATCH | `/students/{id}` | Update |
| POST | `/students/{id}/promote` | `{class_arm_id}` |
| POST | `/students/{id}/graduate` | Marks graduated, creates alumni record |
| DELETE | `/students/{id}` | Delete |

## Results

| Method | Endpoint | Description |
|---|---|---|
| POST | `/results` | `{student_id, subject_id, term_id, components: {CA1, CA2, Exam, ...}}` |
| POST | `/results/{id}/approve` | Principal/VP sign-off |
| POST | `/class-arms/{armId}/subjects/{subjectId}/terms/{termId}/rank` | Computes subject positions |
| GET | `/class-arms/{armId}/terms/{termId}/broadsheet` | Class positions/aggregates |

## Finance

| Method | Endpoint | Description |
|---|---|---|
| POST | `/students/{id}/invoices` | `{term_id}` — generates invoice, applies scholarships |
| POST | `/invoices/{id}/payments` | `{amount, method, gateway_reference?}` |
| GET | `/students/{id}/outstanding` | Balance |
| GET | `/reports/debtors?term_id=` | Every student with an outstanding balance |

## Admission

| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | `/admissions/apply` | none | Public application submission |
| GET | `/admissions/{id}/status` | none | Public status tracking |
| PATCH | `/admissions/{id}/status` | token | Staff review action |
| POST | `/admissions/{id}/register` | token | Converts to a Student record |

## Documents

| Method | Endpoint | Description |
|---|---|---|
| POST | `/documents/generate` | `{document_template_id, student_id, signatory_id?}` |
| GET | `/verify/{uuid}` | Public — QR-scan verification, no auth |

## Notifications, Search, Profile

| Method | Endpoint | Description |
|---|---|---|
| GET | `/notifications` | Paginated list for the logged-in user |
| GET | `/notifications/unread-count` | Badge count |
| PATCH | `/notifications/{id}/read` | Mark one read |
| GET | `/search?q=` | Cross-entity search (students, teachers, applications) |
| GET | `/profile` | Current user |
| PATCH | `/profile` | Update name/phone |
| PATCH | `/profile/password` | `{current_password, new_password, new_password_confirmation}` |

## Roles & Permissions (Super Admin only)

| Method | Endpoint | Description |
|---|---|---|
| GET | `/roles` | All roles with their permissions |
| GET | `/permissions` | All permissions grouped by module |
| PUT | `/roles/{id}/permissions` | `{permission_ids: [...]}` |
| POST | `/users/{id}/roles` | `{role_id, school_id?}` |
| DELETE | `/users/{id}/roles/{roleId}` | Revoke |

## Other modules (Library, Transport, Hostel, Health, Communication, CMS, Reports, Settings)

Follow the same REST pattern — see `routes/api.php` for the complete,
authoritative list with role gates for every endpoint. Each module's
controller (`app/Http/Controllers/Api/`) has inline comments on request
shape and behavior.

## Error format

Validation errors return HTTP 422 with Laravel's standard shape:
```json
{ "message": "The given data was invalid.", "errors": { "field": ["message"] } }
```
Auth failures return 401; permission failures return 403 with a plain
`{"message": "..."}`.