API Reference

REST endpoints for integrating with CipherPoint. All routes are mounted under /api.

Open Interactive Swagger UI

Try every endpoint, see schemas, and copy curl snippets — powered by FastAPI's built-in OpenAPI docs.

Authentication

Most endpoints require a bearer JWT in the Authorization header:

POST /api/auth/signup Create a new account (Turnstile-protected, rate-limited)
POST /api/auth/login Username + password login
POST /api/auth/login/otp/request Send 6-digit OTP to Telegram chat_id
POST /api/auth/login/otp/verify Verify OTP and issue JWT
GET /api/auth/me Return current user profile
POST /api/auth/password-reset/request Request reset token (Telegram)
POST /api/auth/password-reset/confirm Confirm reset with token + new password

Challenges

GET /api/challenges List approved challenges (cached 60s)
GET /api/challenges/community List community-published challenges
GET /api/challenges/{id} Challenge detail + walkthrough if solved/admin
POST /api/challenges/create Admin: create a curated challenge
POST /api/challenges/community/create User: publish a community challenge
PUT /api/challenges/{id} Edit challenge (creator / admin)
DELETE /api/challenges/{id} Delete challenge (creator / admin)
POST /api/challenges/{id}/report Report a challenge to moderators

Submission & Hints

POST /api/challenges/submit Submit a flag (rate-limited, self-solve blocked)
POST /api/hints/unlock Spend coins to unlock a hint

Leaderboard & Profile

GET /api/leaderboard Top users by rank points (cached 30s)
GET /api/profile Current user profile
PUT /api/profile Update display name, bio, avatar
POST /api/profile/daily-bonus Claim daily login bonus (UTC day)

Settings

PUT /api/settings/password Change password (current + new)
PUT /api/settings/notifications Update notification preferences
PUT /api/settings/privacy Update privacy / profile visibility
DELETE /api/settings/account Delete own account (irreversible)
GET /api/settings/telegram/bot-info Public bot username for deep links
PUT /api/settings/telegram Link Telegram chat_id to account
DELETE /api/settings/telegram/disconnect Unlink Telegram

Moderation & Admin

GET /api/moderation/reports Admin: list open reports
POST /api/moderation/reports/{id}/resolve Admin: resolve / dismiss a report
POST /api/admin/emergency-reset-password Admin: reset any user's password (master-key gated)

Media & Health

POST /api/upload/media Upload image / video to Telegram (multipart, 100 MB max)
GET /api/media/{file_id} Proxy Telegram media (with caching & download flag)
GET /api/health DB-aware health check
GET /api/health/bots Status of all Telegram bots
GET /api/config Public client config (sitekey, site info)
GET /healthz Liveness probe (no DB)

Conventions

All requests/responses are application/json unless noted. Access tokens expire in 15 minutes; the frontend silently refreshes them via POST /api/auth/refresh (7-day rotating refresh token). All write endpoints enforce per-IP and per-user rate limits. All admin endpoints require is_admin=true on the JWT subject.