API Contracts¶

Request and response DTOs defined in SimCopilot.Shared. Used by both the desktop app and the API.

All requests requiring authentication must include Authorization: Bearer {jwt}. All responses are wrapped in ApiResponse<T>:

{ "success": true, "data": { ... }, "error": null }

22. Transport DTOs (App ↔ API)¶

These are the data structures that cross the network boundary. Defined in SimCopilot.Shared and used by both the desktop app and the API.

SessionUploadDto¶

Sent by SyncService to POST /v1/sessions.

Field	Why it's sent
`GameId`	Required to find/create the canonical track
`TrackName` / `TrackLayout`	Canonical track lookup key
`VehicleName`	Display and filtering
`RecordedAt`	Client-side timestamp — server stores this rather than `received_at` for accurate feed display
`Laps` (list of `LapSummaryDto`)	Lap times and quality scores — the only per-point data sent
`BestLapMs`	Denormalized best lap for quick leaderboard submission
`WeatherSummary`	AI coaching context
`SessionPhase`	Achievement detection (night race, quali session, etc.)
`ClientSessionId`	Idempotency key — allows safe retry on network failure
`TrackPoints?`	Optional X/Y/Distance samples for track centerline processing

LapSummaryDto¶

Sub-object inside SessionUploadDto. One per lap.

Field	Why it's sent
`LapIndex`	Ordering
`LapTimeMs`	The time to store
`IsValid` / `CountsForSessionTiming`	Quality filtering
`QualityCombined` / `QualityCoherence` / `QualityStability` / `QualityCompleteness`	Server-side leaderboard gating; no need to re-read telemetry
`NumPenalties` / `NumPitstops` / `InPitsAtLapEnd`	Additional validity context

TrackPointDto¶

Sub-object inside SessionUploadDto.TrackPoints. One per sampled position.

Field	Why it's sent
`X`	World-space X coordinate
`Y`	World-space Y coordinate
`Distance`	Track distance in metres at this sample

AiInsightRequestDto / AiChatRequestDto¶

Sent to POST /v1/ai/insights and POST /v1/ai/chat.

Field	Why it's sent
`GameId` / `TrackName` / `TrackLayout` / `VehicleName`	Session context for the AI system prompt
`RefLapMs` / `CurLapMs`	Lap time delta — the AI knows how much time was lost
`Insights[]`	`AnalysisInsight` objects from `AnalysisEngine` — the AI explains these in plain language
`SegmentDeltas[]`	Per-corner time deltas — the AI can identify the biggest problem corners
`Messages[]` (chat only)	Full conversation history — sent each turn so the model has context

Note: Raw telemetry is never sent to the AI endpoint. The analysis engine runs entirely client-side; only the computed findings travel to the server.

LeaderboardSubmitDto¶

Sent by the client to POST /v1/leaderboards/submit.

Field	Why it's sent
`SessionId`	Server-side UUID — the session must already exist (uploaded first)
`LapTimeMs`	The time to rank
`QualityScore`	Must be ≥ 0.8; server validates this independently

UserProfileDto¶

Returned by GET /v1/profile and PATCH /v1/profile.

Field	Description
`Id`	User UUID
`DisplayName`	Shown on leaderboards and feed
`AvatarUrl`	Profile image URL
`Email`	Account email (nullable for OAuth-only accounts)

ApiResponse\<T>¶

All API responses are wrapped in this envelope.

Field	Description
`success`	`true` if the request succeeded, `false` otherwise
`data`	The response payload (null on error)
`error`	Error message string (null on success)