# Chithie Core API Documentation

Welcome to the **Chithie Core API** reference. The backend is built with Django & Django REST Framework (DRF) and serves as an API-only service powering both the Web frontend and Mobile apps.

---

## 🌐 Base URL & Interactive Docs

- **Base URL:** `http://127.0.0.1:8000/api/v1/`
- **Interactive Swagger UI:** [`http://127.0.0.1:8000/api/docs/`](http://127.0.0.1:8000/api/docs/)
- **ReDoc Interactive UI:** [`http://127.0.0.1:8000/api/redoc/`](http://127.0.0.1:8000/api/redoc/)
- **OpenAPI Schema (YAML/JSON):** [`http://127.0.0.1:8000/api/schema/`](http://127.0.0.1:8000/api/schema/)

---

## 🔐 Authentication & Security

- **Session Authentication**: Django session cookies (`sessionid`) are used for authenticated endpoints.
- **CSRF Protection**: State-changing requests (`POST`, `PUT`, `PATCH`, `DELETE`) require a valid `X-CSRFToken` header.
  - Obtain CSRF cookie by performing `GET /api/v1/auth/csrf/`.
- **Permissions**:
  - `AllowAny`: Public endpoints (e.g., login, registration, public profiles, public anonymous inbox submission).
  - `IsAuthenticated`: Signed-in users.
  - `IsVerified`: Signed-in users with email verified and account not suspended.
  - `IsStaffRole` / `IsAdminRole`: Moderation and administration features.

---

## 🩺 System & Health

| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `GET` | `/api/v1/health/` | None | Returns database connectivity & system health status. |

---

## 👤 Accounts & Authentication (`/api/v1/`)

### Authentication & Lifecycle
| Method | Endpoint | Auth | Request Body / Params | Description |
|---|---|---|---|---|
| `GET` | `auth/csrf/` | None | None | Sets the CSRF cookie. |
| `POST` | `auth/register/` | None | `{ "username": "", "email": "", "password": "", "first_name": "", "last_name": "" }` | Registers a new account and queues verification email. |
| `POST` | `auth/login/` | None | `{ "login": "<username_or_email>", "password": "" }` | Authenticates user & sets session cookie. Enforces lockout upon consecutive failures. |
| `POST` | `auth/logout/` | Authenticated | None | Ends current session. |
| `GET` | `auth/verify-email/?token=...` | None | `token` query param | Confirms email address verification. |
| `POST` | `auth/resend-verification/` | Authenticated | None | Queues a fresh email verification link. |
| `POST` | `auth/password-reset/` | None | `{ "email": "" }` | Initiates password reset flow. |
| `POST` | `auth/password-reset/confirm/`| None | `{ "uid": "", "token": "", "new_password": "" }` | Completes password reset with new password. |

### Current User Profile & Settings
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `GET` | `me/` | Authenticated | Retrieve profile details of authenticated user. |
| `PATCH` | `me/` | Authenticated | Update user profile fields (display name, bio, social links, avatar). |
| `POST` | `me/username/` | Authenticated | Change username (rate-limited / policy controlled). |
| `POST` | `me/email/` | Authenticated | Request email update (triggers verification). |
| `POST` | `me/password/` | Authenticated | Change current password. |
| `POST` | `me/delete/` | Authenticated | Permanently delete user account. |
| `GET` | `me/sessions/` | Authenticated | List all active sessions and client devices. |
| `POST` | `me/sessions/revoke-others/` | Authenticated | Invalidate all sessions except the active one. |
| `GET` | `me/warning/` | Authenticated | Fetch and acknowledge staff warning notices. |
| `GET` | `me/suggestions/` | Authenticated | Fetch suggested user profiles. |
| `GET` | `users/{username}/profile/` | None | View a user's public profile info. |

---

## 📬 Anonymous Inboxes & Direct Messaging (`/api/v1/`)

### Public Inbox (Anonymous Q&A)
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `GET` | `inboxes/{slug}/` | None | Get public inbox settings and recipient information. |
| `POST` | `inboxes/{slug}/messages/` | None / Captcha | Post an anonymous message or question to an inbox. |

### Owner Inbox Management
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `GET`, `PATCH` | `inbox/` | IsVerified | Get or update owner inbox preferences (accepting status, pinned message, etc.). |
| `GET` | `inbox/messages/` | IsVerified | List received anonymous messages (supports pagination, filtering by read/starred/archived). |
| `GET`, `PATCH`, `DELETE` | `inbox/messages/{id}/` | IsVerified | Retrieve, update flags (star, archive, read), or soft-delete an inbox message. |

### Direct Messaging (1-to-1 Conversations)
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `GET` | `conversations/` | IsVerified | List all direct message conversations with unread indicators and last message previews. |
| `POST` | `conversations/` | IsVerified | Start or find an existing conversation with another user (`{ "recipient_id": <int> }`). |
| `GET` | `conversations/{id}/messages/` | IsVerified | Paginated history of direct messages in conversation. |
| `POST` | `conversations/{id}/messages/` | IsVerified | Send a message in conversation (`{ "body": "..." }`). |
| `DELETE`| `conversations/{id}/messages/{mid}/` | IsVerified | Delete a message for sender/recipient. |
| `POST` | `conversations/{id}/read/` | IsVerified | Mark conversation messages up to a specific message ID as read. |

---

## 🛡️ Moderation & Policies (`/api/v1/`)

### User Reporting & Appeals
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `POST` | `reports/` | IsVerified | File a moderation report on a message, inbox, or user profile (`{ "target_type": "...", "target_id": ..., "reason": "..." }`). |
| `POST` | `appeals/` | Authenticated | Submit an appeal against an account suspension. |
| `GET` | `policies/documents/public/?doc_type=terms` | None | Read public legal and policy documents. |

### Staff Operations (Staff / Admin Only)
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `GET` | `staff/reports/` | Staff | Review pending reports queue. |
| `GET`, `PATCH` | `staff/reports/{id}/` | Staff | View report details and assign resolutions. |
| `POST` | `staff/reports/{id}/action/` | Staff | Apply moderation action (warn, hide content, suspend user). |
| `GET` | `staff/held/` | Staff | Messages caught by automated content filtering awaiting manual review. |
| `POST` | `staff/held/{id}/release/` | Staff | Release or discard held automated messages. |
| `GET` | `staff/appeals/` | Staff | List appeals submitted by suspended users. |
| `POST` | `staff/appeals/{id}/decide/` | Staff | Approve or reject an appeal. |
| `GET`, `POST` | `staff/policies/rules/` | Admin | List or create automated regex/keyword content moderation rules. |
| `PATCH`, `DELETE` | `staff/policies/rules/{id}/` | Admin | Update or delete content moderation rules. |
| `GET`, `POST` | `staff/policies/domains/` | Staff | Manage disposable email domain blocklist. |
| `DELETE` | `staff/policies/domains/{id}/` | Staff | Remove blocked domain entry. |
| `GET`, `POST` | `staff/policies/documents/` | Admin | Manage terms of service and privacy documents. |

---

## 🔔 Notifications & WebPush (`/api/v1/`)

| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `GET` | `notifications/` | IsVerified | Paginated list of user notifications. Includes `unread_count`. |
| `POST` | `notifications/` | IsVerified | Mark notifications as read (`{ "notification_ids": [...] }` or all). |
| `GET` | `notifications/unread-count/` | IsVerified | Lightweight count of unread notifications. |
| `GET` | `push/vapid-public-key/` | None | Obtain server VAPID public key for browser push subscriptions. |
| `POST` | `push/subscribe/` | IsVerified | Register browser or mobile device push subscription payload. |
| `DELETE` | `push/subscribe/` | IsVerified | Unregister a push subscription. |

---

## ⚙️ Staff Management & Audit (`/api/v1/staff/`)

| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `GET` | `staff/dashboard/` | Staff | Overview metrics, counts, and security status. |
| `GET` | `staff/users/` | Staff | Search and paginate registered users. |
| `GET` | `staff/users/{id}/` | Staff | Comprehensive user audit & profile detail. |
| `POST` | `staff/users/{id}/suspend/` | Staff | Suspend user account. |
| `POST` | `staff/users/{id}/unsuspend/` | Staff | Lift account suspension. |
| `POST` | `staff/users/{id}/role/` | Admin | Promote or modify staff/user roles. |
| `POST` | `staff/users/{id}/delete/` | Admin | Hard-delete or purge user account. |
| `GET` | `staff/audit-log/` | Staff | Cryptographically verifiable system audit log entries. |
| `GET` | `staff/audit-log/export/` | Admin | Export audit logs. |
| `POST` | `staff/audit-log/verify/` | Admin | Verify SHA-256 tamper-evident hash chain integrity of the audit log. |
| `GET` | `staff/security/` | Staff | View recorded authentication and security events. |
| `GET` | `staff/security/export/` | Admin | Export security event logs. |
| `GET`, `PATCH` | `staff/settings/` | Admin | View or adjust global site configuration and feature flags. |
