dotcom-arcade/docs/06-api-reference/README.md

API Reference Documentation

Complete REST API reference for Flashpoint Web backend service.

Base URL

Development: http://localhost:3100/api Production: Configure via DOMAIN environment variable

Authentication

Most endpoints require JWT token in Authorization header:

Authorization: Bearer <access_token>

Obtain tokens via /api/auth/login or /api/auth/register.

Response Format

Success Response

{
  "data": { ... },
  "pagination": { "page": 1, "limit": 50, "total": 1234, "totalPages": 25 }
}

Error Response

{
  "error": { "code": 400, "message": "Validation error: ..." }
}

HTTP Status Codes

• 200 OK - Successful
• 201 Created - Resource created
• 400 Bad Request - Invalid parameters
• 401 Unauthorized - Missing/invalid token
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 409 Conflict - Resource exists
• 500 Internal Server Error - Server error

Rate Limiting

Default: 100 requests per 15 minutes. Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

API Endpoints

Authentication

• POST /api/auth/login
• POST /api/auth/register
• POST /api/auth/refresh
• POST /api/auth/logout
• GET /api/auth/me
• GET /api/auth/setup-status

Games

• GET /api/games
• GET /api/games/filter-options
• GET /api/games/random
• GET /api/games/most-played
• GET /api/games/:id
• GET /api/games/:id/launch
• GET /api/games/:id/related

Discovery

• GET /api/discovery/daily
• GET /api/discovery/playlists

Users

• GET /api/users
• GET /api/users/:id
• POST /api/users
• PATCH /api/users/:id
• DELETE /api/users/:id
• POST /api/users/:id/change-password
• GET /api/users/me/settings
• PATCH /api/users/me/settings
• GET /api/users/me/theme
• PATCH /api/users/me/theme

Roles & Permissions

• GET /api/roles
• GET /api/roles/permissions
• GET /api/roles/:id
• POST /api/roles
• PATCH /api/roles/:id
• PUT /api/roles/:id/permissions
• DELETE /api/roles/:id

Playlists (Flashpoint)

• GET /api/playlists
• GET /api/playlists/:id
• POST /api/playlists
• POST /api/playlists/:id/games
• DELETE /api/playlists/:id/games
• DELETE /api/playlists/:id

User Playlists

• GET /api/user-playlists
• GET /api/user-playlists/stats
• GET /api/user-playlists/:id
• POST /api/user-playlists
• PATCH /api/user-playlists/:id
• DELETE /api/user-playlists/:id
• POST /api/user-playlists/:id/games
• DELETE /api/user-playlists/:id/games
• POST /api/user-playlists/:id/share/enable
• POST /api/user-playlists/:id/share/disable
• POST /api/user-playlists/copy-flashpoint

Favorites

• GET /api/favorites
• GET /api/favorites/game-ids
• GET /api/favorites/games
• GET /api/favorites/stats
• POST /api/favorites/toggle
• POST /api/favorites
• DELETE /api/favorites/:gameId
• POST /api/favorites/batch
• DELETE /api/favorites/batch
• DELETE /api/favorites

Play Tracking

• POST /api/play/start
• POST /api/play/end
• GET /api/play/stats
• GET /api/play/game-stats
• GET /api/play/history
• GET /api/play/top-games
• GET /api/play/activity-over-time
• GET /api/play/games-distribution

Shared Playlists

• GET /api/shared-playlists/:shareToken
• GET /api/shared-playlists/:shareToken/games
• GET /api/shared-playlists/:shareToken/games/:gameId/validate
• POST /api/shared-playlists/:shareToken/generate-access-token
• POST /api/shared-playlists/:shareToken/clone

Community Playlists

• GET /api/community-playlists
• POST /api/community-playlists/download

Downloads

• POST /api/downloads/:id/download
• GET /api/downloads/:id/download/progress
• DELETE /api/downloads/:id/download

Jobs

• GET /api/jobs
• GET /api/jobs/logs/all
• GET /api/jobs/:jobId
• PATCH /api/jobs/:jobId
• POST /api/jobs/:jobId/start
• POST /api/jobs/:jobId/stop
• POST /api/jobs/:jobId/trigger
• GET /api/jobs/:jobId/logs

Platforms & Tags

• GET /api/platforms
• GET /api/tags

Activities & Audit Logs

• GET /api/activities
• GET /api/activities/stats
• GET /api/activities/trend
• GET /api/activities/top-actions
• GET /api/activities/breakdown

Admin & Operations

• GET /api/health
• GET /api/health/detailed
• GET /api/cache/stats
• POST /api/cache/clear
• GET /api/database/status
• POST /api/database/reload
• GET /api/metrics/summary
• GET /api/metrics/endpoints
• GET /api/jobs
• GET /api/github/stars
• GET /api/settings/auth
• PATCH /api/settings/auth
• GET /game-files/*

Domains

• GET /api/domains
• POST /api/domains
• DELETE /api/domains/:id
• PATCH /api/domains/:id/default

System Settings

• GET /api/settings
• GET /api/settings/:category
• PATCH /api/settings/:category
• PATCH /api/settings/:category/:key
• GET /api/settings/_cache/stats
• POST /api/settings/_cache/clear
• GET /api/settings/_cache/permissions/stats
• POST /api/settings/_cache/permissions/clear

Support

For issues: GitHub Issues Documentation: docs/README.md