# API

Base: `/api`. Signed media: `/media/…`. Health: `GET /api/health` (outside the rate-limited mux).

## Response contract

### Success

Ordinary JSON; standard 2xx codes.

### Error

```json
{
  "error": "user-facing message",
  "code": "unauthorized",
  "requestId": "…"
}
```

Response header: `X-Request-ID` (generated by the server if the client did not send one).

The frontend maps these via `toUserError` and `ApiError`.

## Authentication

| Method | Use |
|--------|-----|
| Cookie `pargar_access` | Same-origin browser |
| `Authorization: Bearer <access>` | Tests, tools, in-memory token frontends |
| Cookie / body `refreshToken` | `POST /api/auth/refresh` |

WS: Bearer → subprotocol `bearer` + token → access cookie. Query string is forbidden.

## Public (no login)

| Method | Path | Notes |
|--------|------|--------|
| GET | `/api/auth/captcha` | Image challenge |
| POST | `/api/auth/login` | Login |
| POST | `/api/auth/refresh` | Session rotation |
| POST | `/api/auth/recovery/challenge` | Disabled (404) — public student recovery is off |
| POST | `/api/auth/recovery/reset` | Disabled (404) |
| GET | `/api/auth/register-status` | Whether public registration is on |
| POST | `/api/auth/register` | Public registration |
| GET/POST | `/api/auth/register-invite/{token}` | Invite status / consume |
| GET | `/api/certificates/{publicId}` | Public certificate |
| GET | `/api/community` | Donation / support |
| GET | `/api/sponsors` | Landing sponsors |
| GET | `/api/exports/chats/{token}` | Single-use chat archive download |

## Authenticated (student+)

Key examples:

- `GET /api/auth/me` · `POST /api/auth/logout`
- Tree and lessons: `/api/tree` · `/api/lessons/{id}` · heartbeat · quiz
- `GET /api/leaderboard/weekly` · `GET /api/challenges`
- Events and RSVP: `/api/events…`
- Chat: `/api/chats/…` · upload `/api/chats/upload`
- Notifications, unlock/reset requests
- My certificate: `/api/me/certificate` · issue · physical
- Avatar: `PUT /api/me/avatar` · `POST /api/me/avatar-photo`
- `GET /api/ws`

Full handler list: [`backend/internal/api/router.go`](../backend/internal/api/router.go).

## Staff / admin

Prefix `/api/admin/…`:

- **admin:** stats, users (CRUD, lock, role, reset-password), challenges, announcements, settings, sponsors, physical orders, invites, phone whitelist/blacklist, chat-export (+ tokens)
- **staff (admin + mentor):** learning overview/students, student unlock, chapters / lessons / questions / videos, events
- `GET /api/media/sign` staff only

Mentors do not manage accounts, registration, challenges, announcements, or site settings; they handle learning status and teaching content.

## Versioning

No version prefix for now; call out breaking changes in CHANGELOG/PR. External clients should prefer same-origin cookies or short-lived Bearer tokens.