API Endpoints

Base URL

All API endpoints are prefixed with /api/v1 unless otherwise specified.

Authentication

Public Endpoints

Some endpoints are publicly accessible without authentication.

Protected Endpoints

Protected endpoints require authentication via:

• Telegram Auth: X-Telegram-Auth header with Telegram bot token
• JWT Token: Authorization: Bearer <token> header

Admin Endpoints

Admin endpoints require:

• Admin API Key: X-API-Key header
• JWT Token: Admin JWT token

Endpoint Categories

Health Check

GET /healthz

Check if the API is running.

Response:

{
  "status": "ok"
}

Authentication

POST /api/v1/auth/login

User login endpoint.

Users

GET /api/v1/users

List all users (optional auth for personalized data).

Query Parameters:

• limit (optional): Number of results to return

GET /api/v1/users/paginated

Get paginated list of users.

Query Parameters:

• page (optional): Page number
• limit (optional): Items per page

GET /api/v1/users/profile/:id

Get user profile by ID.

GET /api/v1/users/me

Get current user's profile (auth required).

GET /api/v1/users/recommended

Get recommended users (auth required).

PUT /api/v1/users/socials

Update user social media usernames (auth required).

PUT /api/v1/users/onboarding

Update user onboarding status (auth required).

POST /api/v1/telegram/upsert

Create or update user from Telegram (auth required).

Events

GET /api/v1/events

List all events (public).

GET /api/v1/events/:id

Get event details by ID (optional auth for attendance status).

GET /api/v1/events/slug/:slug

Get event by slug (public).

GET /api/v1/events/:id/attendees

Get event attendees (public).

GET /api/v1/events/my

Get current user's events (auth required).

GET /api/v1/events/conference/:slug

Get conference with events (optional auth).

POST /api/v1/events/attend

Register for an event (auth required).

DELETE /api/v1/events/:id/attend

Cancel event attendance (auth required).

GET /api/v1/events/:id/attendance

Check attendance status (auth required).

POST /api/v1/events/side-event-request

Submit a side event request (auth required).

Conferences

GET /api/v1/conferences

List all conferences (public).

GET /api/v1/conferences/:id

Get conference by ID (public).

GET /api/v1/conferences/slug/:slug

Get conference by slug (public).

GET /api/v1/conferences/slug/:slug/events

Get conference with events (public).

GET /api/v1/conferences/:conference_id/attendees

List conference attendees (optional auth).

GET /api/v1/conferences/:conference_id/agenda

Get conference agenda (public).

GET /api/v1/conferences/slug/:slug/agenda

Get conference agenda by slug (public).

POST /api/v1/conferences/:conference_id/register

Register for conference (auth required).

DELETE /api/v1/conferences/:conference_id/register

Cancel conference registration (auth required).

GET /api/v1/conferences/:conference_id/attendance

Check conference attendance (auth required).

Speakers

GET /api/v1/speakers

List all speakers (public).

GET /api/v1/speakers/featured

Get featured speakers (public).

GET /api/v1/speakers/conference/:id

Get speakers for a conference (public).

GET /api/v1/speakers/:id

Get speaker by ID (public).

GET /api/v1/speakers/:id/profile

Get speaker profile (public).

GET /api/v1/speakers/slug/:slug/socials

Get speaker social links by slug (public).

Quests

GET /api/v1/quests

List all quests (public).

GET /api/v1/quests/featured

Get featured quests (public).

GET /api/v1/quests/:id

Get quest details (optional auth for progress).

GET /api/v1/quests/leaderboard

Get quest leaderboard (public).

GET /api/v1/quests/my

Get user's quests with progress (auth required).

POST /api/v1/quests/:id/start

Start a quest (auth required).

POST /api/v1/quests/:id/request-registration

Request quest registration (auth required).

POST /api/v1/quests/tasks/complete

Complete a quest task (auth required).

GET /api/v1/quests/progress

Get user quest progress (auth required).

GET /api/v1/quests/tasks/:task_id/poll-results

Get poll task results (optional auth).

POST /api/v1/quests/join

Join a quest (public API).

POST /api/v1/quests/complete-task

Complete a quest task (public API).

Connections

POST /api/v1/connections

Send a connection request (auth required).

Request Body:

{
  "recipient_id": 123
}

GET /api/v1/connections

Get all connections (auth required).

Query Parameters:

• status (optional): Filter by status (pending|accepted|rejected)

GET /api/v1/connections/pending

Get pending connection requests (auth required).

GET /api/v1/connections/sent

Get sent pending requests (auth required).

GET /api/v1/connections/connected

Get connected users (auth required).

GET /api/v1/connections/check/:userId

Check connection status with another user (auth required).

PUT /api/v1/connections/:id

Respond to connection request (auth required).

Request Body:

{
  "status": "accepted"
}

Notifications

GET /api/v1/notifications

Get user notifications (auth required).

POST /api/v1/notifications/:id/click

Mark notification as clicked (auth required).

POST /api/v1/notifications/:id/dismiss

Mark notification as dismissed (auth required).

POST /api/v1/notifications/bulk-dismiss

Bulk dismiss notifications (auth required).

PUT /api/v1/notifications/enable

Enable notifications for user (auth required).

Images & Videos

POST /api/v1/images/upload

Upload an image (auth required).

DELETE /api/v1/images

Delete an image (auth required).

POST /api/v1/images/cloudflare/upload

Upload image to Cloudflare R2 (auth required).

POST /api/v1/videos/upload

Upload a video (auth required).

POST /api/v1/videos/cloudflare/upload

Upload video to Cloudflare R2 (auth required).

Feedback

POST /api/v1/feedback

Submit feedback (public).

Partner APIs

KGen Routes

POST /api/v1/partner/kgen/register

Register with KGen (auth required).

POST /api/v1/partner/kgen/verify

Verify OTP (auth required).

POST /api/v1/partner/kgen/refresh-token

Refresh KGen token (auth required).

POST /api/v1/partner/kgen/pog/mint

Mint POG (auth required).

GET /api/v1/partner/kgen/pog/poll

Poll POG status (auth required).

Admin Endpoints

All admin endpoints are prefixed with /api/v1/admin and require admin authentication.

Users

• GET /admin/users - List all users
• POST /admin/users/bulk-import - Bulk import users

Events

• GET /admin/events - List all events
• GET /admin/events/:id - Get event
• POST /admin/events - Create event
• PUT /admin/events/:id - Update event
• DELETE /admin/events/:id - Delete event
• GET /admin/events/pending - Get pending events
• POST /admin/events/:id/approve - Approve event
• POST /admin/events/:id/reject - Reject event
• POST /admin/events/import-luma - Import Luma event
• POST /admin/events/import-all-luma - Import all Luma events

Conferences

• GET /admin/conferences - List conferences
• GET /admin/conferences/:id - Get conference
• POST /admin/conferences - Create conference
• PUT /admin/conferences/:id - Update conference
• DELETE /admin/conferences/:id - Delete conference
• POST /admin/conferences/:conference_id/bulk-upload - Bulk upload attendees

Quests

• GET /admin/quests - List all quests
• GET /admin/quests/:id - Get quest
• POST /admin/quests - Create quest
• PUT /admin/quests/:id - Update quest
• DELETE /admin/quests/:id - Delete quest
• PATCH /admin/quests/:id/toggle-active - Toggle quest active status
• GET /admin/quests/featured - Get featured quests
• GET /admin/quests/:quest_id/pending - Get pending tasks
• POST /admin/quests/tasks/:user_quest_task_id/approve - Approve task
• POST /admin/quests/tasks/:user_quest_task_id/reject - Reject task
• POST /admin/quests/:id/tasks - Create quest task
• PUT /admin/quests/tasks/:id - Update quest task
• DELETE /admin/quests/tasks/:id - Delete quest task
• GET /admin/quests/registration-requests - Get registration requests
• GET /admin/quests/:id/participants - Get quest participants
• GET /admin/quests/:id/export - Export quest data

Notifications

• POST /admin/notifications - Create notification
• POST /admin/notifications/bulk - Bulk create notifications
• POST /admin/notifications/bulk-send - Send bulk notification
• POST /admin/notifications/bulk-send-excel - Send bulk notification from Excel
• GET /admin/notifications/jobs - List notification jobs
• GET /admin/notifications/jobs/:id - Get notification job
• GET /admin/notifications/jobs/:id/stats - Get job statistics
• POST /admin/notifications/jobs/:id/cancel - Cancel notification job
• PUT /admin/notifications/jobs/:id/reschedule - Reschedule notification job
• GET /admin/notifications/template-variables - Get template variables
• GET /admin/notifications/filter-values - Get unique filter values

Enrichment

• POST /admin/enrichment/user/:user_id - Generate enrichment
• POST /admin/enrichment/user/:user_id/sync - Sync enrichment
• POST /admin/enrichment/users - Generate multiple enrichments

Speakers

• GET /admin/speakers - List speakers
• GET /admin/speakers/:id - Get speaker
• POST /admin/speakers - Create speaker
• PUT /admin/speakers/:id - Update speaker
• PUT /admin/speakers/:id/conference - Map speaker to conference

Conference Agenda

• GET /admin/conferences/:conference_id/agenda - List agenda items
• GET /admin/agenda/:id - Get agenda item
• POST /admin/agenda - Create agenda item
• PUT /admin/agenda/:id - Update agenda item
• DELETE /admin/agenda/:id - Delete agenda item

Quest Reminders

• GET /admin/quests/:questId/reminder-templates - Get reminder templates
• POST /admin/quests/:questId/reminder-templates - Create reminder template
• GET /admin/quests/:questId/reminder-templates/:templateId - Get template
• PUT /admin/quests/:questId/reminder-templates/:templateId - Update template
• DELETE /admin/quests/:questId/reminder-templates/:templateId - Delete template
• POST /admin/quests/:questId/reminder-templates/:templateId/set-default - Set default template
• POST /admin/quests/:questId/send-reminder - Send reminder

Feedback

• GET /admin/feedback - Get all feedback

Leaderboard

• GET /admin/leaderboard - Get leaderboard

Error Responses

All endpoints return errors in the following format:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Common HTTP status codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 500 - Internal Server Error