browser/platform_web/api/contracts.md

Frontend API Contracts

API clients and DTO types live here, not inside page components.

Client Groups

• users: user and role APIs.
• serverPlugins: plugin marketplace and installed plugin APIs.
• serverInstances: create server, lifecycle, config read, config diff/approval, scoped files, logs, and detail APIs.
• aiProviders: provider CRUD, test, and model APIs.
• jobs: job status and operation APIs.
• runEndpoints: run endpoint status, lifecycle capabilities, and capacity APIs.
• artifacts: artifact upload/download APIs.
• logs: historical query and tail APIs.
• pluginPageBridge: safe bridge APIs for hosted plugin page.

Every API client must use named request and response types.

Server Management Workflows

• createServerWorkflow posts ServerLifecycleCreateRequest to /server-instances/workflows/create and receives the accepted instance plus install job.
• startServerInstance and stopServerInstance post ServerLifecycleCommandRequest with the current config version and receive the lifecycle job response.
• listServerAdministratorCandidates, addServerAdministrator, and removeServerAdministrator call server membership endpoints so server owners can invite or remove active non-platform-admin server administrators.
• getServerConfig, previewServerConfigDiff, and approveServerConfigWrite call platform-mediated config routes. ServerDetailPage must preview the platform diff first, keep the explicit confirmation step, and dispatch writes only through the approval API.
• dispatchFileOperation posts FileOperationDispatchRequest to /file-operations/dispatch using logical file keys and scoped refs rather than raw host paths.
• listArtifacts, openArtifactDownload, and readArtifactContent use platform artifact routes for available job/server artifacts. Browser reads are chunked through /artifacts/{id}/content and must render only safe filenames, checksums, progress, and platform storage behavior.
• authorizePluginBridge posts PluginBridgeAuthorizeRequest to /plugin-bridge/authorize for preflight decisions.
• executePluginBridge posts PluginBridgeExecuteRequest to /plugin-bridge/execute from host-owned bridge dispatch utilities only. Plugin pages receive typed PluginBridgeExecuteResponse envelopes and never receive the platform API client, bearer token, raw provider key, run socket, host path, or storage credential.
• invokeAI posts AIInvocationRequest to /ai/invocations for platform-mediated AI assistance. Responses carry redacted recommendations, usage metadata, optional reviewable config suggestions, and safe errors; they must not include provider base URLs, key refs, raw keys, or direct provider transport details.
• listRunEndpoints and listJobs provide refresh data for endpoint availability, capacity, and pending lifecycle status.
• Server management DTOs may include bounded ownerUserId and adminUserIds metadata, but must not include raw run credentials, host paths, direct socket details, user password hashes, or AI provider keys.

Redesign Contract Gaps (redesign-platform-web-interactions)

Existing platform APIs already cover server lifecycle, jobs, log stream metadata and cursor query, audit events, users, run endpoints, game plugins, plugin bridge authorization, and AI provider health/test. The redesigned UI additionally declares the following frontend contracts; where the platform backend does not yet serve them, the UI must degrade to a clearly labeled local/unavailable state instead of failing silently:

• POST /api/v1/auth/register (RegisterRequest/AuthSessionResponse): visitor registration. Implemented: the first registered user becomes an active platform administrator; later self-registered users become pending server-scoped users and do not receive platform administrator privileges.
• POST /api/v1/auth/login (LoginRequest/AuthSessionResponse) and POST /api/v1/auth/logout: implemented bearer session lifecycle for authenticated workspace entry.
• GET /api/v1/users/current (CurrentUserResponse): implemented current session identity, roles, profile summary, and theme preference reference for role-aware navigation and default landing.
• PUT /api/v1/users/current/profile (UserProfileUpdateRequest/CurrentUserResponse): implemented current-user profile updates such as display name, avatar reference, phone, QQ, and bounded contact fields.
• PUT /api/v1/users/current/theme (UserThemePreferenceRequest/UserThemePreferenceResponse): implemented per-user theme preferences, including selected palette IDs such as mecha-black or magical-girl, uploaded background reference or safe persisted data URL metadata, and readable overlay preference.
• GET /api/v1/metrics/platform (PlatformResourceUsageResponse): implemented platform-level CPU/memory/disk usage and LLM connectivity summary for the overview first screen.
• GET /api/v1/metrics/server-instances (ServerMetricsListResponse): implemented per-server online state, player count, TPS, latency, CPU/memory/disk for server cards and the server detail header.
• GET /api/v1/server-instances/{id}/config (ServerConfigResponse): implemented readable configuration content for diff-based editing.
• POST /api/v1/server-instances/{id}/config/diff (ServerConfigDiffPreviewRequest/ServerConfigDiffPreviewResponse) and POST /api/v1/server-instances/{id}/config/approve (ServerConfigWriteApprovalRequest/ServerConfigWriteDispatchResponse): implemented platform-mediated config write review and approval. Manual config edits and AI suggestion applies must not create generic config.write jobs through POST /api/v1/jobs.
• POST /api/v1/file-operations/dispatch (FileOperationDispatchRequest/FileOperationDispatchResponse): implemented scoped file operation dispatch using logical keys and refs only.
• POST /api/v1/ai/config-suggestions (LlmConfigSuggestionRequest/LlmConfigSuggestionResponse) and POST /api/v1/ai/invocations (AIInvocationRequest/AIInvocationResponse): platform-mediated AI recommendation or diff scoped to one server. Provider keys stay in platform/; responses carry only recommendation text, usage metadata, and reviewable suggestions, never keys or provider secrets.
• Per-server plugin controls are rendered from installed plugin manifests (bridgeActions, lifecycleActions, pages, declaredPermissions); a richer declared-control schema remains a future plugin contract. Hosted bridge execution uses POST /api/v1/plugin-bridge/execute for server context, scoped file, log, job, artifact reference, and AI action envelopes instead of direct plugin fetches to platform internals.
• Operation/job traceability reuses GET /api/v1/jobs, GET /api/v1/jobs/{id}, POST /api/v1/jobs/{id}/cancel, and GET /api/v1/audit-events; the frontend wraps these in one visible operation lifecycle per user intent.
• Log filtering by level/keyword/time/source is applied client-side over POST /api/v1/log-streams/query (LogStreamCursorRequest) results until the platform exposes server-side filters.