{"openapi":"3.0.0","paths":{"/status":{"get":{"operationId":"HealthController_healthCheck","parameters":[],"responses":{"204":{"description":"Service is healthy and running. No content returned."}},"summary":"Get API health.","tags":["Health"]}},"/api/client-token":{"get":{"operationId":"ClientTokenController_list","parameters":[],"responses":{"200":{"description":"Information about your client tokens.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ListResponseDto"}}}}},"400":{"description":"The request is invalid."},"401":{"description":"User session invalid or expired."},"404":{"description":"User not found."}},"security":[{"bearer":[]}],"summary":"Get a list of your client tokens.","tags":["ClientToken"]},"post":{"description":"Client tokens are not allowed on this route.","operationId":"ClientTokenController_generate","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequestDto"}}}},"responses":{"200":{"description":"Client token has been generated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateResponseDto"}}}},"400":{"description":"The request body is invalid."},"401":{"description":"User session invalid or expired."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"User not found."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Generate a client token.","tags":["ClientToken","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route."}}},"/api/client-token/{tokenId}":{"delete":{"description":"Client tokens are not allowed on this route.","operationId":"ClientTokenController_delete","parameters":[{"name":"tokenId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Client token has been deleted."},"400":{"description":"Client token id is invalid."},"401":{"description":"User session invalid or expired."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"User or client token not found or expired."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Delete a client token.","tags":["ClientToken","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route."}}},"/api/client-token/{tokenId}/regenerate":{"post":{"description":"Client tokens are not allowed on this route.","operationId":"ClientTokenController_regenerate","parameters":[{"name":"tokenId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Client token has been regenerated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateResponseDto"}}}},"400":{"description":"Client token id is invalid."},"401":{"description":"User session invalid or expired."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"User or client token not found or expired."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Regenerate a client token.","tags":["ClientToken","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route."}}},"/api/v1/users/{id}/block":{"post":{"operationId":"UsersController_blockUser","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"User blocked."},"401":{"description":"Unauthorized."},"404":{"description":"User not found."},"409":{"description":"User already blocked or cannot block self."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"Block a user.","tags":["Users"]},"delete":{"operationId":"UsersController_unblockUser","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"User unblocked."},"401":{"description":"Unauthorized."},"404":{"description":"User or blocked user not found."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"Unblock a user.","tags":["Users"]}},"/api/v1/users/me/blocked":{"get":{"operationId":"UsersController_listBlockedUsers","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UserResponseDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"List blocked users.","tags":["Users"]}},"/api/v1/users/{id}/friend-request":{"post":{"description":"Client tokens are not allowed on this route: Interaction by client tokens is not supported.","operationId":"UsersController_sendFriendRequest","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/FriendRequestResponseDto"}}}}}},"400":{"description":"Invalid request."},"401":{"description":"Unauthorized."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"User not found."},"406":{"description":"Client token version is outdated."},"409":{"description":"Friend request already exists."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"Send a friend request to a user.","tags":["Users","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: Interaction by client tokens is not supported."}},"delete":{"description":"Client tokens are not allowed on this route: Interaction by client tokens is not supported.","operationId":"UsersController_cancelFriendRequest","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Friend request cancelled."},"401":{"description":"Unauthorized."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"No pending friend request to cancel."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"Cancel a friend request you sent to a user.","tags":["Users","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: Interaction by client tokens is not supported."}}},"/api/v1/users/me/friend-request/{requestId}/accept":{"patch":{"operationId":"UsersController_acceptFriendRequest","parameters":[{"name":"requestId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/FriendRequestResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"Request not found."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"Accept a friend request.","tags":["Users"]}},"/api/v1/users/me/friend-request/{requestId}/reject":{"patch":{"operationId":"UsersController_rejectFriendRequest","parameters":[{"name":"requestId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/FriendRequestResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"Request not found."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"Reject a friend request.","tags":["Users"]}},"/api/v1/users/me/{id}/unfriend":{"patch":{"operationId":"UsersController_unfriendUser","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"User unfriended."},"400":{"description":"Invalid request."},"401":{"description":"Unauthorized."},"404":{"description":"User not found."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"Unfriend a user.","tags":["Users"]}},"/api/v1/users/me/friend-requests":{"get":{"operationId":"UsersController_listIncomingFriendRequests","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FriendRequestResponseDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"List incoming friend requests.","tags":["Users"]}},"/api/v1/users/me/friend-requests/outgoing":{"get":{"operationId":"UsersController_listOutgoingFriendRequests","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FriendRequestResponseDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"List outgoing (sent) friend requests.","tags":["Users"]}},"/api/v1/users/me/friends":{"get":{"operationId":"UsersController_listFriends","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UserResponseDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"List accepted friends.","tags":["Users"]}},"/api/v1/users/me/presence":{"post":{"operationId":"UsersController_updatePresence","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePresenceRequestDto"}}}},"responses":{"201":{"description":""},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"Update the caller current social presence.","tags":["Users"]}},"/api/v1/users/me/presence/heartbeat":{"post":{"operationId":"UsersController_presenceHeartbeat","parameters":[],"responses":{"201":{"description":""},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"Liveness heartbeat (CH-628). Marks the caller online and refreshes last_seen within the idle window. ONLINE layer only — does NOT require being in a world and never touches the rich-presence ACTIVITY layer. The app shell beats this on any authed, visible tab.","tags":["Users"]}},"/api/v1/users/me/presence/activity":{"post":{"operationId":"UsersController_setPresenceActivity","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetPresenceActivityRequestDto"}}}},"responses":{"201":{"description":""},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"Set the caller rich-presence activity for the world they are in. Server-authoritative: only the authenticated player, only their current world. Rate-limited + moderated.","tags":["Users"]},"delete":{"operationId":"UsersController_clearPresenceActivity","parameters":[],"responses":{"200":{"description":""},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"Clear the caller rich-presence activity.","tags":["Users"]}},"/api/v1/users/me/friends/presence":{"get":{"operationId":"UsersController_listFriendPresence","parameters":[],"responses":{"200":{"description":""},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"List friends with joinable presence metadata.","tags":["Users"]}},"/api/v1/users/{id}/report":{"post":{"operationId":"UsersController_reportUser","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportUserRequestDto"}}}},"responses":{"400":{"description":"Invalid report."},"401":{"description":"Unauthorized."},"404":{"description":"User not found."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"Report a user for moderation review.","tags":["Users"]}},"/api/v1/users":{"get":{"description":"Retrieve public information about users based on search query. Can chain multiple queries together.","operationId":"UsersController_retrieveAll","parameters":[{"name":"id","required":false,"in":"query","description":"The user IDs to search for.","schema":{"type":"array","items":{"type":"string"}}},{"name":"username","required":false,"in":"query","description":"The usernames to search for.","schema":{"type":"array","items":{"type":"string"}}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by.","schema":{"type":"string","enum":["username"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in.","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of users to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UserResponseDto"}}}}}}},"400":{"description":"Invalid query parameters."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Search for users by username or ID","tags":["Users"]}},"/api/v1/users/admin/all":{"get":{"description":"Retrieve paginated list of all users with complete information (excluding password hash). Supports filtering by search string (username/displayName/bio), username, email, and country. Admin access required.","operationId":"UsersController_retrieveAllForAdmin","parameters":[{"name":"search","required":false,"in":"query","description":"Search string to match against username, displayName, and bio","schema":{"example":"john","type":"string"}},{"name":"username","required":false,"in":"query","description":"Filter by exact username","schema":{"example":"johndoe123","type":"string"}},{"name":"email","required":false,"in":"query","description":"Filter by email address","schema":{"example":"user@example.com","type":"string"}},{"name":"country","required":false,"in":"query","description":"Filter by country code (2-letter ISO code)","schema":{"example":"US","type":"string"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UserAdminResponseDto"}}}}}}},"400":{"description":"Invalid query parameters."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Admin: Retrieve all users with full information","tags":["Users"]}},"/api/v1/users/me":{"get":{"description":"Returns the authenticated user profile. Note: Does not include relationship flags (friend, blocked) as these are not applicable to your own profile.","operationId":"UsersController_retrieveMe","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UserMeResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"User not found."}},"security":[{"bearer":[]},{"bearer":[]},{"oauth_access":[]}],"summary":"Retrieve the user associated with the bearer token.","tags":["Users","OAuth2 Support"],"x-oauth2-support":{"supported":true,"description":"OAuth2 is supported on this route","minimumScopes":["identify"]}},"patch":{"description":"Client tokens are not allowed on this route: This route is not supported for security reasons.","operationId":"UsersController_updateMe","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UserMeResponseDto"}}}}}},"400":{"description":"The request body is invalid."},"401":{"description":"Session expired or invalid."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"User not found."},"406":{"description":"Client token version is outdated."},"409":{"description":"Username already taken."},"429":{"description":"You're making changes too quickly. Please wait a moment."}},"security":[{"bearer":[]},{"bearer":[]}],"summary":"Update the user associated with the bearer token.","tags":["Users","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported for security reasons."}}},"/api/v1/users/by-username/{username}":{"get":{"operationId":"UsersController_retrieveOneByUsername","parameters":[{"name":"username","required":true,"in":"path","description":"The username of the user (case-insensitive exact match).","schema":{"example":"exampleuser1","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UserResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"User not found."}},"security":[{"bearer":[]}],"summary":"Retrieve a user by exact username match.","tags":["Users"]}},"/api/v1/users/{userId}":{"get":{"operationId":"UsersController_retrieveOne","parameters":[{"name":"userId","required":true,"in":"path","description":"The ID of the user.","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UserResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"User not found."}},"security":[{"bearer":[]}],"summary":"Retrieve a user by ID.","tags":["Users"]}},"/api/v1/users/me/reviews":{"get":{"operationId":"UsersController_getMyReviews","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Limit (items per page)","schema":{"default":10,"example":10,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserReviewsCollectionResponseDto"}}}},"400":{"description":"Invalid query parameters."},"401":{"description":"Unauthorized."},"404":{"description":"User not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]},{"bearer":[]},{"oauth_access":[]}],"summary":"Get all reviews for the authenticated user (paginated).","tags":["Users"]}},"/api/v1/users/me/favorites/packages/{packageId}":{"post":{"operationId":"UsersController_addFavoritePackage","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Package added to favorites."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Add a package to favorites.","tags":["Users"]},"delete":{"operationId":"UsersController_removeFavoritePackage","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Package removed from favorites."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Remove a package from favorites.","tags":["Users"]}},"/api/v1/users/me/favorites/servers/{serverId}":{"post":{"operationId":"UsersController_addFavoriteServer","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Server added to favorites."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Add a server to favorites.","tags":["Users"]},"delete":{"operationId":"UsersController_removeFavoriteServer","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Server removed from favorites."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Remove a server from favorites.","tags":["Users"]}},"/api/v1/users/me/favorites/packages":{"get":{"operationId":"UsersController_listFavoritePackages","parameters":[{"name":"name","required":false,"in":"query","description":"The name of the package to search for.","schema":{"type":"string"}},{"name":"slug","required":false,"in":"query","description":"The slug of the package to search for.","schema":{"type":"string"}},{"name":"showOnlyPrivate","required":false,"in":"query","description":"Show only private packages that the authenticated user has access to (either as owner or via role-granted access). Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"hideMine","required":false,"in":"query","description":"Hide packages created by the authenticated user. Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"type","required":false,"in":"query","description":"The package types to search for.","schema":{"type":"array","items":{"type":"string","enum":["World","Map","QRE","Vehicle","Character","Character Preset","Weapon","Wearable","Animation","Structure","Interior","Tool","Effect","Sound","Script","Addon","EDL","Other"]}}},{"name":"excludeType","required":false,"in":"query","description":"The package types to exclude from the search.","schema":{"type":"array","items":{"type":"string","enum":["World","Map","QRE","Vehicle","Character","Character Preset","Weapon","Wearable","Animation","Structure","Interior","Tool","Effect","Sound","Script","Addon","EDL","Other"]}}},{"name":"contentRating","required":false,"in":"query","description":"The content rating of the package to search for.","schema":{"type":"string","enum":["Everyone","Teen","Mature","Adult"]}},{"name":"tags","required":false,"in":"query","description":"The tags of the package to search for.","schema":{"type":"array","items":{"type":"string"}}},{"name":"publishedAfter","required":false,"in":"query","description":"The date to search for packages published after.","schema":{"format":"date-time","type":"string"}},{"name":"publishedBefore","required":false,"in":"query","description":"The date to search for packages published before.","schema":{"format":"date-time","type":"string"}},{"name":"updatedAfter","required":false,"in":"query","description":"The date to search for packages updated after.","schema":{"format":"date-time","type":"string"}},{"name":"updatedBefore","required":false,"in":"query","description":"The date to search for packages updated before.","schema":{"format":"date-time","type":"string"}},{"name":"lastReleaseAfter","required":false,"in":"query","description":"The date to search for packages with latest release after this date.","schema":{"format":"date-time","type":"string"}},{"name":"lastReleaseBefore","required":false,"in":"query","description":"The date to search for packages with latest release before this date.","schema":{"format":"date-time","type":"string"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by.","schema":{"type":"string","enum":["name","slug","createdAt","updatedAt","publishedAt","lastReleaseAt"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in.","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of servers to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PackageCollectionResponseDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"List favorite packages (paginated).","tags":["Users"]}},"/api/v1/users/me/favorites/servers":{"get":{"operationId":"UsersController_listFavoriteServers","parameters":[{"name":"name","required":false,"in":"query","description":"The name of the server to search for.","schema":{"type":"string"}},{"name":"slug","required":false,"in":"query","description":"The slug of the server to search for.","schema":{"type":"string"}},{"name":"gameMode","required":false,"in":"query","description":"The game mode to search for.","schema":{"type":"array","items":{"type":"string","enum":["Sandbox","Roleplay","Survival","Free For All","Team Deathmatch","Capture The Flag","Social"]}}},{"name":"hostingType","required":false,"in":"query","description":"The hosting type to search for.","schema":{"type":"array","items":{"type":"string","enum":["Dedicated","Local","Provisioned"]}}},{"name":"contentRating","required":false,"in":"query","description":"The content rating to search for.","schema":{"type":"array","items":{"type":"string","enum":["Everyone","Teen","Mature","Adult"]}}},{"name":"tags","required":false,"in":"query","description":"The tags to search for.","schema":{"type":"array","items":{"type":"string"}}},{"name":"publishedAfter","required":false,"in":"query","description":"The date to search for servers published after.","schema":{"format":"date-time","type":"string"}},{"name":"publishedBefore","required":false,"in":"query","description":"The date to search for servers published before.","schema":{"format":"date-time","type":"string"}},{"name":"updatedAfter","required":false,"in":"query","description":"The date to search for servers updated after.","schema":{"format":"date-time","type":"string"}},{"name":"updatedBefore","required":false,"in":"query","description":"The date to search for servers updated before.","schema":{"format":"date-time","type":"string"}},{"name":"packageId","required":false,"in":"query","description":"The package ID to search for servers that use any version of this package.","schema":{"type":"string"}},{"name":"packageVersionId","required":false,"in":"query","description":"The package version ID to search for servers that use this specific package version (either as worldId or in packageVersions).","schema":{"type":"string"}},{"name":"showOnlyPrivate","required":false,"in":"query","description":"Show only private servers that the authenticated user has access to (either as owner or whitelisted). Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"hideMine","required":false,"in":"query","description":"Hide servers owned by the authenticated user. Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by.","schema":{"type":"string","enum":["name","slug","currentPlayers","visits","createdAt","updatedAt","publishedAt"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in.","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of servers to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServerResponseDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"List favorite servers (paginated).","tags":["Users"]}},"/api/v1/users/me/favorites/instant-worlds/{worldId}":{"post":{"operationId":"UsersController_addFavoriteInstantWorld","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"World added to favorites."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Add an Instant World to favorites.","tags":["Users"]},"delete":{"operationId":"UsersController_removeFavoriteInstantWorld","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"World removed from favorites."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Remove an Instant World from favorites.","tags":["Users"]}},"/api/v1/users/me/favorites/instant-worlds/ids":{"get":{"operationId":"UsersController_listFavoriteInstantWorldIds","parameters":[],"responses":{"200":{"description":"Favorited world ids."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"List the ids of all Instant Worlds the caller has favorited.","tags":["Users"]}},"/api/v1/users/me/favorites/instant-worlds":{"get":{"operationId":"UsersController_listFavoriteInstantWorlds","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Free-text match on world title/slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InstantWorldResponseDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"List favorite Instant Worlds (paginated).","tags":["Users"]}},"/api/v1/users/me/favorites/worlds/{worldId}":{"post":{"operationId":"UsersController_addFavoriteWorld","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"World added to favorites."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Add a world to favorites.","tags":["Users"]},"delete":{"operationId":"UsersController_removeFavoriteWorld","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"World removed from favorites."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Remove a world from favorites.","tags":["Users"]}},"/api/v1/users/me/favorites/worlds/ids":{"get":{"operationId":"UsersController_listFavoriteWorldIds","parameters":[],"responses":{"200":{"description":"Favorited world ids."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"List the ids of all worlds the caller has favorited.","tags":["Users"]}},"/api/v1/users/me/favorites/worlds":{"get":{"operationId":"UsersController_listFavoriteWorlds","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Free-text match on world title/slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InstantWorldResponseDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"List favorite worlds (paginated).","tags":["Users"]}},"/api/v1/users/me/favorites/items/{itemId}":{"post":{"operationId":"UsersController_addFavoriteUniversalItem","parameters":[{"name":"itemId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Item added to favorites."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Add a universal item to favorites.","tags":["Users"]},"delete":{"operationId":"UsersController_removeFavoriteUniversalItem","parameters":[{"name":"itemId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Item removed from favorites."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Remove a universal item from favorites.","tags":["Users"]}},"/api/v1/users/me/favorites/items/ids":{"get":{"operationId":"UsersController_listFavoriteUniversalItemIds","parameters":[],"responses":{"200":{"description":"Favorited item ids."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"List the ids of all universal items the caller has favorited.","tags":["Users"]}},"/api/v1/users/me/favorites/items":{"get":{"operationId":"UsersController_listFavoriteUniversalItems","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Free-text match on item title/slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UniversalItemResponseDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"List favorite universal items (paginated).","tags":["Users"]}},"/api/v1/users/me/favorites/homes/{homeId}":{"post":{"operationId":"UsersController_addFavoriteHome","parameters":[{"name":"homeId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Home added to favorites."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Add a home to favorites.","tags":["Users"]},"delete":{"operationId":"UsersController_removeFavoriteHome","parameters":[{"name":"homeId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Home removed from favorites."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Remove a home from favorites.","tags":["Users"]}},"/api/v1/users/me/favorites/homes/ids":{"get":{"operationId":"UsersController_listFavoriteHomeIds","parameters":[],"responses":{"200":{"description":"Favorited home ids."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"List the ids of all homes the caller has favorited.","tags":["Users"]}},"/api/v1/users/me/favorites/homes":{"get":{"operationId":"UsersController_listFavoriteHomes","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"visibility","required":false,"in":"query","schema":{"type":"string","enum":["draft","private","friends","unlisted","public"]}},{"name":"category","required":false,"in":"query","schema":{"type":"string","enum":["apartment","social_room","showroom","event_space","storefront","gallery","game_room","creator_hub","other"]}},{"name":"tag","required":false,"in":"query","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","schema":{"default":"recent","type":"string","enum":["recent","most_visited","most_expensive","most_items"]}},{"name":"maxContentMaturity","required":false,"in":"query","description":"Maximum content maturity to include. Unrated content is treated as general.","schema":{"type":"string","enum":["general","teen","mature","adult"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"List favorite homes (paginated).","tags":["Users"]}},"/api/v1/user-reviews":{"post":{"description":"Client tokens are not allowed on this route: This route is not supported at this time.","operationId":"UserReviewsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserReviewRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UserReviewResponseDto"}}}}}},"401":{"description":"Unauthorized."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"User or package not found."},"406":{"description":"Client token version is outdated."},"409":{"description":"User has already reviewed this package."}},"security":[{"bearer":[]}],"summary":"Create a user review for a package.","tags":["UserReviews","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported at this time."}}},"/api/v1/user-reviews/{packageId}":{"patch":{"operationId":"UserReviewsController_update","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserReviewRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UserReviewResponseDto"}}}}}},"400":{"description":"Invalid packageId format. Must be a valid UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized."},"404":{"description":"Review or package not found."}},"security":[{"bearer":[]}],"summary":"Update a user review for a package.","tags":["UserReviews"]},"put":{"deprecated":true,"operationId":"UserReviewsController_updatePut","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserReviewRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UserReviewResponseDto"}}}}}},"400":{"description":"Invalid packageId format. Must be a valid UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized."},"404":{"description":"Review or package not found."}},"security":[{"bearer":[]}],"summary":"Update a user review for a package.","tags":["UserReviews"]},"delete":{"operationId":"UserReviewsController_delete","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Review deleted successfully."},"400":{"description":"Invalid packageId format. Must be a valid UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized."},"404":{"description":"Review or package not found."}},"security":[{"bearer":[]}],"summary":"Delete a user review for a package.","tags":["UserReviews"]}},"/api/v1/wallet/me":{"get":{"operationId":"WalletController_getMyWallet","parameters":[],"responses":{"200":{"description":"User wallet retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletMeResponseDto"}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get wallet for authenticated user","tags":["Wallet"]}},"/api/v1/wallet":{"post":{"description":"Client tokens are not allowed on this route: This route does not support client tokens for security reasons.","operationId":"WalletController_createUserWallet","parameters":[],"responses":{"201":{"description":"User wallet created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletResponseDto"}}}},"401":{"description":"Unauthorized."},"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Create a new wallet for the authenticated user","tags":["Wallet","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route does not support client tokens for security reasons."}}},"/api/v1/wallet/debug/top-up/me":{"post":{"description":"Development/test-only helper. Creates a real economy transaction and credits the caller wallet, so /wallet/me and /transactions/me reflect the top-up.","operationId":"WalletController_debugTopUpMyWallet","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DebugWalletTopUpRequestDto"}}}},"responses":{"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[DEBUG] Add real LIX to the authenticated test wallet","tags":["Wallet","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route does not support client tokens for security reasons."}}},"/api/v1/eula/latest":{"get":{"description":"Public endpoint to retrieve the latest version of the EULA. Returns the EULA with the highest version number.","operationId":"EulaController_getLatestEula","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/EulaResponseDto"}}}}}},"404":{"description":"No EULA found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"Get the latest EULA version","tags":["EULA"]}},"/api/v1/eula/status":{"get":{"description":"Authenticated endpoint to check if the user has accepted any EULA and whether they have accepted the latest version. Returns acceptance status including version information.","operationId":"EulaController_checkUserEulaStatus","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/EulaAcceptanceStatusDto"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"User or EULA not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Check user EULA acceptance status","tags":["EULA","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported for security reasons."}}},"/api/v1/eula/admin":{"post":{"description":"Admin-only endpoint to create a new EULA. The version number is automatically incremented from the latest EULA. The authenticated admin user is recorded as the creator.","operationId":"EulaController_createEula","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEulaDto"}}}},"responses":{"201":{"description":"EULA created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EulaResponseDto"}}}},"400":{"description":"Invalid request data or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Create a new EULA","tags":["EULA"]},"get":{"description":"Admin-only endpoint to retrieve a paginated list of all EULAs. Supports sorting by version number, creation date, update date, or title.","operationId":"EulaController_getEulas","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"default":10,"example":10,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Sort by field","schema":{"default":"versionNumber","example":"versionNumber","type":"string","enum":["versionNumber","createdAt","updatedAt","title"]}},{"name":"sortOrder","required":false,"in":"query","description":"Sort order","schema":{"default":"DESC","example":"DESC","type":"string","enum":["ASC","DESC"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EulaResponseDto"}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get paginated list of EULAs","tags":["EULA"]}},"/api/v1/eula/admin/{id}":{"patch":{"description":"Admin-only endpoint to update an existing EULA. Can update title and/or content. The updatedBy field is automatically set to the authenticated admin user.","operationId":"EulaController_updateEula","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEulaDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/EulaResponseDto"}}}}}},"400":{"description":"Invalid request data or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"EULA not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update an existing EULA","tags":["EULA"]}},"/api/v1/privacy-policy/latest":{"get":{"description":"Public endpoint to retrieve the latest version of the Privacy Policy. Returns the Privacy Policy with the highest version number.","operationId":"PrivacyPolicyController_getLatestPrivacyPolicy","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PrivacyPolicyResponseDto"}}}}}},"404":{"description":"No Privacy Policy found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"Get the latest Privacy Policy version","tags":["Privacy Policy"]}},"/api/v1/privacy-policy/status":{"get":{"description":"Authenticated endpoint to check if the user has accepted any Privacy Policy and whether they have accepted the latest version. Returns acceptance status including version information.","operationId":"PrivacyPolicyController_checkUserPrivacyPolicyStatus","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PrivacyPolicyAcceptanceStatusDto"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"User or Privacy Policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Check user Privacy Policy acceptance status","tags":["Privacy Policy","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported for security reasons."}}},"/api/v1/privacy-policy/admin":{"post":{"description":"Admin-only endpoint to create a new Privacy Policy. The version number is automatically incremented from the latest Privacy Policy. The authenticated admin user is recorded as the creator.","operationId":"PrivacyPolicyController_createPrivacyPolicy","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePrivacyPolicyDto"}}}},"responses":{"201":{"description":"Privacy Policy created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyPolicyResponseDto"}}}},"400":{"description":"Invalid request data or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Create a new Privacy Policy","tags":["Privacy Policy"]},"get":{"description":"Admin-only endpoint to retrieve a paginated list of all Privacy Policies. Supports sorting by version number, creation date, update date, or title.","operationId":"PrivacyPolicyController_getPrivacyPolicies","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"default":10,"example":10,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Sort by field","schema":{"default":"versionNumber","example":"versionNumber","type":"string","enum":["versionNumber","createdAt","updatedAt","title"]}},{"name":"sortOrder","required":false,"in":"query","description":"Sort order","schema":{"default":"DESC","example":"DESC","type":"string","enum":["ASC","DESC"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PrivacyPolicyResponseDto"}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get paginated list of Privacy Policies","tags":["Privacy Policy"]}},"/api/v1/privacy-policy/admin/{id}":{"patch":{"description":"Admin-only endpoint to update an existing Privacy Policy. Can update title and/or content. The updatedBy field is automatically set to the authenticated admin user.","operationId":"PrivacyPolicyController_updatePrivacyPolicy","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePrivacyPolicyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PrivacyPolicyResponseDto"}}}}}},"400":{"description":"Invalid request data or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Privacy Policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update an existing Privacy Policy","tags":["Privacy Policy"]}},"/api/v1/helixgram/feed":{"get":{"operationId":"HelixgramController_getFeed","parameters":[{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get the Helixgram feed.","tags":["Helixgram"]}},"/api/v1/helixgram/feed/me":{"get":{"operationId":"HelixgramController_getAuthenticatedFeed","parameters":[{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}},{"name":"scope","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get the authenticated Helixgram feed.","tags":["Helixgram"]}},"/api/v1/helixgram/stories":{"get":{"operationId":"HelixgramController_getStories","parameters":[{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get active Helixgram stories.","tags":["Helixgram"]},"post":{"operationId":"HelixgramController_createStory","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHelixgramStoryDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Create a Helixgram story.","tags":["Helixgram"]}},"/api/v1/helixgram/stories/me":{"get":{"operationId":"HelixgramController_getAuthenticatedStories","parameters":[{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get active Helixgram stories for this viewer.","tags":["Helixgram"]}},"/api/v1/helixgram/users/{userId}/posts":{"get":{"operationId":"HelixgramController_getUserPosts","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get Helixgram posts for a profile.","tags":["Helixgram"]}},"/api/v1/helixgram/users/{userId}/posts/me":{"get":{"operationId":"HelixgramController_getAuthenticatedUserPosts","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get profile Helixgram posts for this viewer.","tags":["Helixgram"]}},"/api/v1/helixgram/users/{userId}/stories":{"get":{"operationId":"HelixgramController_getUserStories","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get active Helixgram stories for a profile.","tags":["Helixgram"]}},"/api/v1/helixgram/users/{userId}/stories/me":{"get":{"operationId":"HelixgramController_getAuthenticatedUserStories","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get profile Helixgram stories for this viewer.","tags":["Helixgram"]}},"/api/v1/helixgram/posts/{postId}":{"get":{"operationId":"HelixgramController_getPostById","parameters":[{"name":"postId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get a single Helixgram post by id (permalink / mention notification deep link).","tags":["Helixgram"]},"delete":{"operationId":"HelixgramController_deletePost","parameters":[{"name":"postId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Delete one of your Helixgram posts.","tags":["Helixgram"]}},"/api/v1/helixgram/stories/{storyId}":{"get":{"operationId":"HelixgramController_getStoryById","parameters":[{"name":"storyId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get a single active Helixgram story by id (mention notification deep link).","tags":["Helixgram"]},"delete":{"operationId":"HelixgramController_deleteStory","parameters":[{"name":"storyId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Delete one of your Helixgram stories.","tags":["Helixgram"]}},"/api/v1/helixgram/users/{userId}/social":{"get":{"operationId":"HelixgramController_getUserSocial","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get Helixgram follow counts for a user.","tags":["Helixgram"]}},"/api/v1/helixgram/users/{userId}/social/me":{"get":{"operationId":"HelixgramController_getAuthenticatedUserSocial","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get Helixgram follow counts for this viewer.","tags":["Helixgram"]}},"/api/v1/helixgram/discover/users":{"get":{"operationId":"HelixgramController_discoverUsers","parameters":[{"name":"q","required":true,"in":"query","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Discover Helixgram users.","tags":["Helixgram"]}},"/api/v1/helixgram/discover/users/me":{"get":{"operationId":"HelixgramController_discoverUsersForViewer","parameters":[{"name":"q","required":true,"in":"query","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Discover Helixgram users for this viewer.","tags":["Helixgram"]}},"/api/v1/helixgram/users/{userId}/follow":{"post":{"operationId":"HelixgramController_followUser","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Follow a Helixgram user.","tags":["Helixgram"]},"delete":{"operationId":"HelixgramController_unfollowUser","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Unfollow a Helixgram user.","tags":["Helixgram"]}},"/api/v1/helixgram/posts":{"post":{"operationId":"HelixgramController_createPost","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHelixgramPostDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Create a Helixgram post.","tags":["Helixgram"]}},"/api/v1/helixgram/reports":{"post":{"operationId":"HelixgramController_reportContent","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHelixgramReportDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Report Helixgram content for moderation.","tags":["Helixgram"]}},"/api/v1/helixgram/admin/reports":{"get":{"operationId":"HelixgramController_getReports","parameters":[{"name":"status","required":true,"in":"query","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get Helixgram moderation reports.","tags":["Helixgram"]}},"/api/v1/helixgram/admin/reports/{reportId}/status":{"patch":{"operationId":"HelixgramController_updateReportStatus","parameters":[{"name":"reportId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHelixgramReportStatusDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update a Helixgram report status.","tags":["Helixgram"]}},"/api/v1/helixgram/posts/{postId}/like":{"post":{"operationId":"HelixgramController_likePost","parameters":[{"name":"postId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Like a Helixgram post.","tags":["Helixgram"]},"delete":{"operationId":"HelixgramController_unlikePost","parameters":[{"name":"postId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Unlike a Helixgram post.","tags":["Helixgram"]}},"/api/v1/helixgram/posts/{postId}/comments":{"post":{"operationId":"HelixgramController_addComment","parameters":[{"name":"postId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHelixgramCommentDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Comment on a Helixgram post.","tags":["Helixgram"]}},"/api/v1/helixgram/posts/{postId}/comments/{commentId}":{"delete":{"operationId":"HelixgramController_deleteComment","parameters":[{"name":"postId","required":true,"in":"path","schema":{"type":"string"}},{"name":"commentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Delete a Helixgram comment.","tags":["Helixgram"]}},"/api/v1/helixgram/posts/{postId}/share-to-story":{"post":{"operationId":"HelixgramController_sharePostToStory","parameters":[{"name":"postId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Share a Helixgram post to your own story.","tags":["Helixgram"]}},"/api/v1/helixgram/stories/{storyId}/view":{"post":{"operationId":"HelixgramController_viewStory","parameters":[{"name":"storyId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Record that you viewed a Helixgram story.","tags":["Helixgram"]}},"/api/v1/helixgram/stories/{storyId}/viewers":{"get":{"operationId":"HelixgramController_getStoryViewers","parameters":[{"name":"storyId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get who has viewed your own Helixgram story.","tags":["Helixgram"]}},"/api/v1/helixgram/close-friends/me":{"get":{"operationId":"HelixgramController_getCloseFriends","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List your Helixgram close friends.","tags":["Helixgram"]}},"/api/v1/helixgram/close-friends/{userId}":{"post":{"operationId":"HelixgramController_addCloseFriend","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Add a user to your Helixgram close friends.","tags":["Helixgram"]},"delete":{"operationId":"HelixgramController_removeCloseFriend","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Remove a user from your Helixgram close friends.","tags":["Helixgram"]}},"/api/v1/notifications":{"get":{"operationId":"NotificationsController_getNotifications","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":50,"default":20,"example":20,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by notification status","schema":{"type":"string","enum":["UNREAD","READ"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/NotificationResponseDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get user notifications with pagination","tags":["Notifications"]},"delete":{"operationId":"NotificationsController_deleteAllNotifications","parameters":[],"responses":{"204":{"description":"All notifications deleted."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Delete all of the current user notifications","tags":["Notifications"]}},"/api/v1/notifications/unread-count":{"get":{"operationId":"NotificationsController_getUnreadCount","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UnreadCountResponseDto"}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get unread notification count","tags":["Notifications"]}},"/api/v1/notifications/preferences":{"get":{"operationId":"NotificationsController_getPreferences","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/NotificationPreferenceResponseDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get all notification preferences","tags":["Notifications"]},"patch":{"operationId":"NotificationsController_updatePreferences","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateNotificationPreferenceDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/NotificationPreferenceResponseDto"}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Update notification preferences","tags":["Notifications"]}},"/api/v1/notifications/{notificationId}/read":{"patch":{"operationId":"NotificationsController_markAsRead","parameters":[{"name":"notificationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/NotificationResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"Notification not found."}},"security":[{"bearer":[]}],"summary":"Mark a notification as read","tags":["Notifications"]}},"/api/v1/notifications/read-all":{"patch":{"operationId":"NotificationsController_markAllAsRead","parameters":[],"responses":{"204":{"description":"All notifications marked as read."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Mark all notifications as read","tags":["Notifications"]}},"/api/v1/notifications/{notificationId}":{"delete":{"operationId":"NotificationsController_deleteNotification","parameters":[{"name":"notificationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Notification deleted successfully."},"401":{"description":"Unauthorized."},"404":{"description":"Notification not found."}},"security":[{"bearer":[]}],"summary":"Delete a notification","tags":["Notifications"]}},"/api/oauth2/info":{"get":{"operationId":"OAuthController_oauth2Info","parameters":[{"name":"client_id","required":true,"in":"query","schema":{"type":"string"}},{"name":"redirect_uri","required":true,"in":"query","schema":{"type":"string"}},{"name":"scope","required":true,"in":"query","schema":{"type":"string"}},{"name":"response_type","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Information about the OAuth2.0 application.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InfoResponseDto"}}}},"400":{"description":"The request is invalid."},"401":{"description":"User session invalid or expired."},"403":{"description":"Un-whitelisted redirect URI or scope."},"404":{"description":"Client ID not found."}},"security":[{"bearer":[]}],"summary":"Get information about an OAuth2.0 authorization request.","tags":["OAuth"]}},"/api/oauth2/authorize":{"put":{"description":"Client tokens are not allowed on this route: OAuth2 authorization is not supported with client tokens.","operationId":"OAuthController_oauth2Authorize","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizeRequestDto"}}}},"responses":{"200":{"description":"OAuth2.0 authorization code has been generated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizeResponseDto"}}}},"400":{"description":"The request body is invalid."},"401":{"description":"User session invalid or expired."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"Client ID not found."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Confirm a OAuth2.0 authorization.","tags":["OAuth","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: OAuth2 authorization is not supported with client tokens."}}},"/api/oauth2/token":{"post":{"description":"Only accepts application/x-www-form-urlencoded body","operationId":"OAuthController_oauth2Token","parameters":[],"requestBody":{"required":true,"description":"OAuth2 token request body","content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/TokenRequestFormDto"}}}},"responses":{"200":{"description":"OAuth2.0 access token has been generated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponseDto"}}}},"400":{"description":"The request body is invalid."},"401":{"description":"Client ID or secret missing or invalid."},"403":{"description":"Incorrect client credentials or redirect uri."},"404":{"description":"Client ID or code not found."}},"security":[{"client_credentials":[]}],"summary":"Generate OAuth2.0 Token","tags":["OAuth"]}},"/api/v1/oidc/userinfo":{"get":{"description":"Validates JWT tokens and returns user information for Epic Games EOS integration","operationId":"OidcController_userInfo","parameters":[],"responses":{"200":{"description":"The access token is valid and trusted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OidcUserInfoResponseDto"}}}},"401":{"description":"The access token is invalid, expired, or otherwise cannot be trusted."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"The user was not found in the account system."},"406":{"description":"Client token version is outdated."},"500":{"description":"Something went wrong and the authentication service could not complete the request."}},"security":[{"bearer":[]}],"summary":"OIDC UserInfo endpoint for Epic Games EOS token validation","tags":["Oidc","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported for security reasons."}}},"/auth/login":{"post":{"operationId":"AuthController_login","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequestDto"}}}},"responses":{"200":{"description":"The user has been authenticated and a token has been returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponseDto"}}}},"400":{"description":"Invalid request."},"401":{"description":"Email not verified."},"403":{"description":"Account is suspended."},"500":{"description":"Failed to login user."}},"summary":"Authenticate a user and return an access token.","tags":["Auth"]}},"/auth/refresh":{"post":{"operationId":"AuthController_refresh","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshRequestDto"}}}},"responses":{"200":{"description":"A token has been generated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshResponseDto"}}}},"400":{"description":"Invalid request."},"401":{"description":"Email not verified."},"403":{"description":"Account is suspended."},"404":{"description":"User not found."},"500":{"description":"Failed to refresh token."}},"summary":"Uses a refresh token to obtain a new access token.","tags":["Auth"]}},"/auth/register":{"post":{"operationId":"AuthController_register","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequestDto"}}}},"responses":{"201":{"description":"The user has been successfully registered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserMeResponseDto"}}}},"400":{"description":"Invalid request or invalid invite code."},"409":{"description":"User already exists."}},"summary":"Register a new user.","tags":["Auth"]}},"/auth/email-code/request":{"post":{"operationId":"AuthController_requestEmailCode","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestEmailCodeRequestDto"}}}},"responses":{"200":{"description":"The one-time code has been sent if email sending is configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestEmailCodeResponseDto"}}}},"400":{"description":"The email is invalid."}},"summary":"Send a one-time email login code.","tags":["Auth"]}},"/auth/email-code/verify":{"post":{"operationId":"AuthController_verifyEmailCode","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyEmailCodeRequestDto"}}}},"responses":{"200":{"description":"The user has been authenticated and a token has been returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponseDto"}}}},"400":{"description":"The request is invalid, the code expired, or username is required."},"409":{"description":"The requested username is unavailable."}},"summary":"Verify a one-time email code, creating a passwordless account if needed.","tags":["Auth"]}},"/auth/request-password-reset":{"post":{"operationId":"AuthController_requestPasswordReset","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestPasswordResetRequestDto"}}}},"responses":{"200":{"description":"Generates password reset token and sends a reset password email to the user if the user exists."},"400":{"description":"The email or username is invalid."}},"summary":"Start a new password reset process.","tags":["Auth"]}},"/auth/reset-password":{"post":{"operationId":"AuthController_resetPassword","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetPasswordRequestDto"}}}},"responses":{"200":{"description":"The password has been reset."},"400":{"description":"The request body is invalid."}},"summary":"Reset a user's password.","tags":["Auth"]}},"/auth/verify-password-reset-token":{"post":{"operationId":"AuthController_verifyPasswordResetToken","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyPasswordResetTokenRequestDto"}}}},"responses":{"200":{"description":"The password reset token is valid."},"400":{"description":"The password reset token is invalid or expired."}},"summary":"Check whether a password reset token is valid without consuming it.","tags":["Auth"]}},"/auth/request-email-verify":{"post":{"operationId":"AuthController_requestEmailVerify","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestEmailVerifyRequestDto"}}}},"responses":{"200":{"description":"Generates email verification token and sends a email verification email to the user if the user exists."},"400":{"description":"The email is invalid."}},"summary":"Start a new email verification process.","tags":["Auth"]}},"/auth/verify-email":{"post":{"operationId":"AuthController_verifyEmail","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyEmailRequestDto"}}}},"responses":{"200":{"description":"The email has been verified."},"400":{"description":"The request body is invalid."}},"summary":"Verify a user's email.","tags":["Auth"]},"get":{"deprecated":true,"operationId":"AuthController_verifyEmailGet","parameters":[{"name":"token","required":true,"in":"query","description":"The email verification token of the user.","schema":{"example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30","type":"string"}}],"responses":{"200":{"description":"The email has been verified."},"400":{"description":"The request body is invalid."}},"summary":"(TEMPORARY) Verify a user's email. This endpoint is only used for testing purposes.","tags":["Auth"]}},"/api/v1/admin/users/_probe/balances":{"get":{"operationId":"AdminBalancesController_probeUserBalances","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Probe the mounted balances endpoint using the caller's account.","tags":["Admin / Balances"]}},"/api/v1/admin/users/{userId}/balances":{"get":{"operationId":"AdminBalancesController_getUserBalances","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Read a user's LIX balance.","tags":["Admin / Balances"]},"post":{"operationId":"AdminBalancesController_setUserBalances","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetBalancesRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Set or delta-adjust a user's LIX balance. Returns the new balances.","tags":["Admin / Balances"]}},"/api/v1/admin/balances":{"get":{"operationId":"AdminBalancesController_getBalancesConvenience","parameters":[{"name":"email","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Read balances by ?email=, or the calling admin's own balances when no email is given.","tags":["Admin / Balances"]},"post":{"operationId":"AdminBalancesController_setBalancesConvenience","parameters":[{"name":"email","required":false,"in":"query","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetBalancesRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Set balances by ?email=, or the calling admin's own balances when no email is given. Returns the new balances.","tags":["Admin / Balances"]}},"/api/v1/invites/preview/{inviteCode}":{"get":{"description":"Public preview for signup/referral pages. Returns inviter display context and eligibility without redeeming.","operationId":"InvitesController_previewInviteCode","parameters":[{"name":"inviteCode","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InvitePreviewResponseDto"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Preview an invite code","tags":["Invites"]}},"/api/v1/invites/admin/grant-quota":{"post":{"description":"Admin-only endpoint to grant additional invite code generation quota to a user. Automatically enables the allowedToGenerateInviteCode permission. Bypasses permission checks.","operationId":"InvitesController_grantInviteQuota","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantInviteQuotaRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/GrantInviteQuotaResponseDto"}}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Grant invite code quota to a user","tags":["Invites"]}},"/api/v1/invites/admin/user-settings":{"patch":{"description":"Admin-only endpoint to update a user invite quota and/or permission to generate invite codes. Can adjust quota by positive or negative amounts.","operationId":"InvitesController_updateUserInviteSettings","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserInviteSettingsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UpdateUserInviteSettingsResponseDto"}}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update user invite settings","tags":["Invites"]}},"/api/v1/invites/admin/{inviteCode}":{"patch":{"description":"Admin-only endpoint to update invite code attributes. Currently supports updating the canBeRedeemed flag to enable or disable code redemption.","operationId":"InvitesController_updateInviteCode","parameters":[{"name":"inviteCode","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInviteCodeRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InviteResponseDto"}}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Invite code not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update invite code attributes","tags":["Invites"]}},"/api/v1/invites/admin/all":{"get":{"description":"Admin-only endpoint to retrieve all invite codes with comprehensive filtering options including creator, distributor, redeemed status, dates, and more. Supports pagination.","operationId":"InvitesController_getAllInviteCodes","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"creatorUsername","required":false,"in":"query","description":"Filter by creator username (partial match, case-insensitive)","schema":{"example":"john_doe","type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"Filter by creator user ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"redeemedByUsername","required":false,"in":"query","description":"Filter by redeemed-by username (partial match, case-insensitive)","schema":{"example":"jane_smith","type":"string"}},{"name":"redeemedByUserId","required":false,"in":"query","description":"Filter by redeemed-by user ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"inviteCode","required":false,"in":"query","description":"Filter by specific invite code","schema":{"example":"ABC123","type":"string"}},{"name":"isRedeemed","required":false,"in":"query","description":"Filter by redeemed status (true = redeemed, false = not redeemed)","schema":{"example":true,"type":"boolean"}},{"name":"canBeRedeemed","required":false,"in":"query","description":"Filter by canBeRedeemed status","schema":{"example":true,"type":"boolean"}},{"name":"createdBefore","required":false,"in":"query","description":"Filter codes created before this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"createdAfter","required":false,"in":"query","description":"Filter codes created after this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}},{"name":"redeemedBefore","required":false,"in":"query","description":"Filter codes redeemed before this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"redeemedAfter","required":false,"in":"query","description":"Filter codes redeemed after this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InviteResponseDto"}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get all invite codes with filters","tags":["Invites"]}},"/api/v1/invites/admin/redemptions":{"get":{"description":"Admin-only audit endpoint for referral redemptions by code, inviter, invitee, status, and deny/reward reason.","operationId":"InvitesController_getAdminInviteRedemptions","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"inviteCode","required":false,"in":"query","schema":{"example":"ABC123","type":"string"}},{"name":"inviterUserId","required":false,"in":"query","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"inviteeUserId","required":false,"in":"query","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["pending","accepted","rejected","rewarded","reward_failed"]}},{"name":"reason","required":false,"in":"query","description":"Matches either denyReason or rewardReason exactly.","schema":{"example":"duplicate_account_redemption","type":"string"}},{"name":"createdAfter","required":false,"in":"query","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}},{"name":"createdBefore","required":false,"in":"query","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InviteRedemptionResponseDto"}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Search invite redemptions","tags":["Invites"]}},"/api/v1/invites/admin/settle-pending":{"post":{"description":"Repair sweep. Pays out every accepted/failed referral whose invited user now satisfies the eligibility rule (today: finished the onboarding quest). Idempotent — a referral already paid is skipped, so re-running never double-grants.","operationId":"InvitesController_settlePendingReferrals","parameters":[],"responses":{"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Settle referrals whose eligibility has cleared","tags":["Invites"]}},"/api/v1/invites/generate":{"post":{"description":"Generate a new invite code. For admins: automatically increments quota and bypasses permission checks. For regular users: requires allowedToGenerateInviteCode permission and checks quota availability. Returns the newly created invite code.","operationId":"InvitesController_generateInviteCode","parameters":[],"responses":{"201":{"description":"Invite code generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteResponseDto"}}}},"400":{"description":"Invite code quota exhausted (non-admin users only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"User lacks permission to generate invite codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Generate a new invite code","tags":["Invites"]}},"/api/v1/invites/my-codes":{"get":{"description":"Retrieve invite codes created by the authenticated user. Supports filtering by redeemed status, dates, and more. Supports pagination.","operationId":"InvitesController_getMyInviteCodes","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"creatorUsername","required":false,"in":"query","description":"Filter by creator username (partial match, case-insensitive)","schema":{"example":"john_doe","type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"Filter by creator user ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"redeemedByUsername","required":false,"in":"query","description":"Filter by redeemed-by username (partial match, case-insensitive)","schema":{"example":"jane_smith","type":"string"}},{"name":"redeemedByUserId","required":false,"in":"query","description":"Filter by redeemed-by user ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"inviteCode","required":false,"in":"query","description":"Filter by specific invite code","schema":{"example":"ABC123","type":"string"}},{"name":"isRedeemed","required":false,"in":"query","description":"Filter by redeemed status (true = redeemed, false = not redeemed)","schema":{"example":true,"type":"boolean"}},{"name":"canBeRedeemed","required":false,"in":"query","description":"Filter by canBeRedeemed status","schema":{"example":true,"type":"boolean"}},{"name":"createdBefore","required":false,"in":"query","description":"Filter codes created before this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"createdAfter","required":false,"in":"query","description":"Filter codes created after this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}},{"name":"redeemedBefore","required":false,"in":"query","description":"Filter codes redeemed before this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"redeemedAfter","required":false,"in":"query","description":"Filter codes redeemed after this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InviteResponseDto"}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get my invite codes","tags":["Invites"]}},"/api/v1/invites/me/dashboard":{"get":{"description":"Returns the authenticated user referral invite code and aggregate redemption/reward counts.","operationId":"InvitesController_getMyInviteDashboard","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InviteDashboardResponseDto"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get my invite dashboard","tags":["Invites"]}},"/api/v1/invites/me/history":{"get":{"description":"Returns auditable redemption rows for invite codes owned by the authenticated user.","operationId":"InvitesController_getMyInviteHistory","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"creatorUsername","required":false,"in":"query","description":"Filter by creator username (partial match, case-insensitive)","schema":{"example":"john_doe","type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"Filter by creator user ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"redeemedByUsername","required":false,"in":"query","description":"Filter by redeemed-by username (partial match, case-insensitive)","schema":{"example":"jane_smith","type":"string"}},{"name":"redeemedByUserId","required":false,"in":"query","description":"Filter by redeemed-by user ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"inviteCode","required":false,"in":"query","description":"Filter by specific invite code","schema":{"example":"ABC123","type":"string"}},{"name":"isRedeemed","required":false,"in":"query","description":"Filter by redeemed status (true = redeemed, false = not redeemed)","schema":{"example":true,"type":"boolean"}},{"name":"canBeRedeemed","required":false,"in":"query","description":"Filter by canBeRedeemed status","schema":{"example":true,"type":"boolean"}},{"name":"createdBefore","required":false,"in":"query","description":"Filter codes created before this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"createdAfter","required":false,"in":"query","description":"Filter codes created after this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}},{"name":"redeemedBefore","required":false,"in":"query","description":"Filter codes redeemed before this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"redeemedAfter","required":false,"in":"query","description":"Filter codes redeemed after this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InviteRedemptionResponseDto"}}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get my invite redemption history","tags":["Invites"]}},"/api/v1/invites/me/reward-status":{"get":{"description":"Returns referral reward grant rows where the authenticated user is the beneficiary.","operationId":"InvitesController_getMyRewardStatus","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"creatorUsername","required":false,"in":"query","description":"Filter by creator username (partial match, case-insensitive)","schema":{"example":"john_doe","type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"Filter by creator user ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"redeemedByUsername","required":false,"in":"query","description":"Filter by redeemed-by username (partial match, case-insensitive)","schema":{"example":"jane_smith","type":"string"}},{"name":"redeemedByUserId","required":false,"in":"query","description":"Filter by redeemed-by user ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"inviteCode","required":false,"in":"query","description":"Filter by specific invite code","schema":{"example":"ABC123","type":"string"}},{"name":"isRedeemed","required":false,"in":"query","description":"Filter by redeemed status (true = redeemed, false = not redeemed)","schema":{"example":true,"type":"boolean"}},{"name":"canBeRedeemed","required":false,"in":"query","description":"Filter by canBeRedeemed status","schema":{"example":true,"type":"boolean"}},{"name":"createdBefore","required":false,"in":"query","description":"Filter codes created before this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"createdAfter","required":false,"in":"query","description":"Filter codes created after this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}},{"name":"redeemedBefore","required":false,"in":"query","description":"Filter codes redeemed before this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"redeemedAfter","required":false,"in":"query","description":"Filter codes redeemed after this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InviteRewardGrantResponseDto"}}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get my referral reward status","tags":["Invites"]}},"/api/v1/invites/accept":{"post":{"description":"Existing accounts are audited and marked ineligible; signup redemption is handled by /auth/register.","operationId":"InvitesController_acceptInvite","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptInviteRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InviteRedemptionResponseDto"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Accept an invite for the authenticated account","tags":["Invites"]}},"/api/v1/analytics/events":{"post":{"operationId":"AnalyticsController_captureEvent","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureAnalyticsEventDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsCaptureResponseDto"}}}},"401":{"description":"Invalid bearer token."}},"security":[{"bearer":[]}],"summary":"Capture one analytics event.","tags":["Analytics"]}},"/api/v1/analytics/events/batch":{"post":{"operationId":"AnalyticsController_captureBatch","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptureAnalyticsBatchDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsCaptureResponseDto"}}}},"401":{"description":"Invalid bearer token."}},"security":[{"bearer":[]}],"summary":"Capture a batch of analytics events.","tags":["Analytics"]}},"/api/v1/analytics/admin/journeys":{"get":{"operationId":"AnalyticsController_getStaffJourney","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"userId","required":false,"in":"query","schema":{"type":"string"}},{"name":"anonymousId","required":false,"in":"query","schema":{"type":"string"}},{"name":"sessionId","required":false,"in":"query","schema":{"type":"string"}},{"name":"eventName","required":false,"in":"query","schema":{"type":"string","enum":["user_signed_up","user_logged_in","anonymous_user_identified","invite_sent","invite_link_copied","invite_landed","invite_modal_viewed","invite_opened","invite_accepted","invite_signup_started","invite_signup_completed","invite_reward_granted","invite_reward_denied","referral_source_captured","ftue_started","ftue_step_started","ftue_step_viewed","ftue_step_completed","ftue_step_skipped","ftue_deep_link_destination_entered","ftue_tablet_opened","ftue_hud_minimized","ftue_hud_expanded","ftue_hud_dismissed","ftue_welcome_notification_sent","ftue_reward_claimed","ftue_item_placed","ftue_showcase_home_visited","ftue_item_scanned","ftue_world_joined","ftue_world_objective_completed","ftue_friend_edge_created","ftue_invite_link_copied","ftue_currencies_learned","ftue_item_purchased","ftue_first_post","ftue_creation_published","ftue_completed","ftue_abandoned","session_started","session_ended","world_entered","world_loaded","world_load_failed","world_exited","world_heartbeat","instance_joined","instance_left","friend_request_sent","friend_request_accepted","party_created","party_joined","share_clicked","item_viewed","item_purchased","item_equipped","home_visited","creator_product_viewed","creator_product_purchased","creator_earned","lix_spent","coins_spent","report_submitted","moderation_action_created","content_rating_changed","trust_state_changed","client_error_seen","api_error_seen","developer_publish_cta_clicked","developer_publish_modal_viewed","developer_publish_path_selected","developer_install_command_copied","developer_publish_prompt_copied"]}},{"name":"worldId","required":false,"in":"query","schema":{"type":"string"}},{"name":"creatorId","required":false,"in":"query","schema":{"type":"string"}},{"name":"platform","required":false,"in":"query","schema":{"type":"string","enum":["web","mobile_webview","ios","android","unreal","server"]}},{"name":"from","required":false,"in":"query","schema":{"example":"2026-07-01T00:00:00.000Z","type":"string"}},{"name":"to","required":false,"in":"query","schema":{"example":"2026-07-31T23:59:59.999Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffAnalyticsJourneyResponseDto"}}}},"401":{"description":"Invalid bearer token."}},"security":[{"bearer":[]}],"summary":"Staff-only user journey and event timeline.","tags":["Analytics"]}},"/api/v1/analytics/admin/funnels/ftue":{"get":{"operationId":"AnalyticsController_getFtueFunnel","parameters":[{"name":"from","required":false,"in":"query","schema":{"example":"2026-07-01T00:00:00.000Z","type":"string"}},{"name":"to","required":false,"in":"query","schema":{"example":"2026-07-31T23:59:59.999Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsFunnelResponseDto"}}}},"401":{"description":"Invalid bearer token."}},"security":[{"bearer":[]}],"summary":"Staff-only FTUE funnel summary.","tags":["Analytics"]}},"/api/v1/analytics/admin/funnels/invites":{"get":{"operationId":"AnalyticsController_getInviteFunnel","parameters":[{"name":"from","required":false,"in":"query","schema":{"example":"2026-07-01T00:00:00.000Z","type":"string"}},{"name":"to","required":false,"in":"query","schema":{"example":"2026-07-31T23:59:59.999Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsFunnelResponseDto"}}}},"401":{"description":"Invalid bearer token."}},"security":[{"bearer":[]}],"summary":"Staff-only invite funnel summary.","tags":["Analytics"]}},"/api/v1/analytics/admin/export/events":{"get":{"operationId":"AnalyticsController_exportEvents","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":500,"default":250,"type":"number"}},{"name":"userId","required":false,"in":"query","schema":{"type":"string"}},{"name":"anonymousId","required":false,"in":"query","schema":{"type":"string"}},{"name":"sessionId","required":false,"in":"query","schema":{"type":"string"}},{"name":"eventName","required":false,"in":"query","schema":{"type":"string","enum":["user_signed_up","user_logged_in","anonymous_user_identified","invite_sent","invite_link_copied","invite_landed","invite_modal_viewed","invite_opened","invite_accepted","invite_signup_started","invite_signup_completed","invite_reward_granted","invite_reward_denied","referral_source_captured","ftue_started","ftue_step_started","ftue_step_viewed","ftue_step_completed","ftue_step_skipped","ftue_deep_link_destination_entered","ftue_tablet_opened","ftue_hud_minimized","ftue_hud_expanded","ftue_hud_dismissed","ftue_welcome_notification_sent","ftue_reward_claimed","ftue_item_placed","ftue_showcase_home_visited","ftue_item_scanned","ftue_world_joined","ftue_world_objective_completed","ftue_friend_edge_created","ftue_invite_link_copied","ftue_currencies_learned","ftue_item_purchased","ftue_first_post","ftue_creation_published","ftue_completed","ftue_abandoned","session_started","session_ended","world_entered","world_loaded","world_load_failed","world_exited","world_heartbeat","instance_joined","instance_left","friend_request_sent","friend_request_accepted","party_created","party_joined","share_clicked","item_viewed","item_purchased","item_equipped","home_visited","creator_product_viewed","creator_product_purchased","creator_earned","lix_spent","coins_spent","report_submitted","moderation_action_created","content_rating_changed","trust_state_changed","client_error_seen","api_error_seen","developer_publish_cta_clicked","developer_publish_modal_viewed","developer_publish_path_selected","developer_install_command_copied","developer_publish_prompt_copied"]}},{"name":"worldId","required":false,"in":"query","schema":{"type":"string"}},{"name":"creatorId","required":false,"in":"query","schema":{"type":"string"}},{"name":"platform","required":false,"in":"query","schema":{"type":"string","enum":["web","mobile_webview","ios","android","unreal","server"]}},{"name":"from","required":false,"in":"query","schema":{"example":"2026-07-01T00:00:00.000Z","type":"string"}},{"name":"to","required":false,"in":"query","schema":{"example":"2026-07-31T23:59:59.999Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsExportResponseDto"}}}},"401":{"description":"Invalid bearer token."}},"security":[{"bearer":[]}],"summary":"Staff-only bounded export of normalized analytics events.","tags":["Analytics"]}},"/api/v1/analytics/admin/actors/detail":{"get":{"operationId":"AnalyticsController_getActorDetail","parameters":[{"name":"from","required":false,"in":"query","schema":{"example":"2026-07-01T00:00:00.000Z","type":"string"}},{"name":"to","required":false,"in":"query","schema":{"example":"2026-07-31T23:59:59.999Z","type":"string"}},{"name":"actorType","required":false,"in":"query","schema":{"type":"string","enum":["user","anonymous","session"]}},{"name":"actorId","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":250,"default":80,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsActorDetailResponseDto"}}}},"401":{"description":"Invalid bearer token."}},"security":[{"bearer":[]}],"summary":"Staff-only detail view for one user, anonymous visitor, or session.","tags":["Analytics"]}},"/api/v1/analytics/admin/ai/insight-scaffold":{"get":{"operationId":"AnalyticsController_getInsightScaffold","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsInsightJobScaffoldDto"}}}},"401":{"description":"Invalid bearer token."}},"security":[{"bearer":[]}],"summary":"Staff-only scaffold for future AI insight jobs.","tags":["Analytics"]}},"/api/v1/analytics/creator/worlds/{worldId}/rollup":{"get":{"operationId":"AnalyticsController_getCreatorWorldRollup","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","schema":{"example":"2026-07-01T00:00:00.000Z","type":"string"}},{"name":"to","required":false,"in":"query","schema":{"example":"2026-07-31T23:59:59.999Z","type":"string"}},{"name":"grain","required":false,"in":"query","schema":{"type":"string","enum":["hour","day"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorAnalyticsRollupResponseDto"}}}},"401":{"description":"Invalid bearer token."}},"security":[{"bearer":[]}],"summary":"Creator-safe aggregate analytics for one owned world. Raw timelines are never exposed.","tags":["Analytics"]}},"/api/v1/analytics/creator/homes/{homeId}/rollup":{"get":{"operationId":"AnalyticsController_getOwnerHomeRollup","parameters":[{"name":"homeId","required":true,"in":"path","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","schema":{"example":"2026-07-01T00:00:00.000Z","type":"string"}},{"name":"to","required":false,"in":"query","schema":{"example":"2026-07-31T23:59:59.999Z","type":"string"}},{"name":"grain","required":false,"in":"query","schema":{"type":"string","enum":["hour","day"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorAnalyticsRollupResponseDto"}}}},"401":{"description":"Invalid bearer token."}},"security":[{"bearer":[]}],"summary":"Owner-safe aggregate visit analytics for one owned home. Raw timelines are never exposed; the `worlds` breakdown is always empty.","tags":["Analytics"]}},"/api/v1/analytics/creator/rollup":{"get":{"operationId":"AnalyticsController_getCreatorRollup","parameters":[{"name":"from","required":false,"in":"query","schema":{"example":"2026-07-01T00:00:00.000Z","type":"string"}},{"name":"to","required":false,"in":"query","schema":{"example":"2026-07-31T23:59:59.999Z","type":"string"}},{"name":"grain","required":false,"in":"query","schema":{"type":"string","enum":["hour","day"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorAnalyticsRollupResponseDto"}}}},"401":{"description":"Invalid bearer token."}},"security":[{"bearer":[]}],"summary":"Creator-safe aggregate analytics across the caller owned worlds.","tags":["Analytics"]}},"/api/v1/steam-keys/me":{"get":{"description":"Returns the steam key assigned to the authenticated user, or null if none is assigned.","operationId":"SteamKeysController_getMyKey","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/SteamKeyResponseDto"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Get my steam key","tags":["Steam Keys","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported at this time."}}},"/api/v1/steam-keys/admin":{"post":{"description":"Admin-only endpoint to create a single steam key.","operationId":"SteamKeysController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSteamKeyRequestDto"}}}},"responses":{"201":{"description":"Steam key created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SteamKeyResponseDto"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Steam key already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Create a new steam key","tags":["Steam Keys"]},"get":{"description":"Admin-only endpoint to retrieve all steam keys with filtering options including assigned status, user, and key search. Supports pagination.","operationId":"SteamKeysController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"userId","required":false,"in":"query","description":"Filter by assigned user ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"username","required":false,"in":"query","description":"Filter by assigned username (partial match, case-insensitive)","schema":{"example":"john_doe","type":"string"}},{"name":"isAssigned","required":false,"in":"query","description":"Filter by assigned status (true = assigned, false = unassigned)","schema":{"example":false,"type":"boolean"}},{"name":"key","required":false,"in":"query","description":"Search by key value (partial match, case-insensitive)","schema":{"example":"XXXXX","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SteamKeyResponseDto"}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get all steam keys with filters","tags":["Steam Keys"]}},"/api/v1/steam-keys/admin/bulk":{"post":{"description":"Admin-only endpoint to create multiple steam keys. Skips duplicates and returns count of created/skipped keys.","operationId":"SteamKeysController_bulkCreate","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCreateSteamKeysRequestDto"}}}},"responses":{"201":{"description":"Bulk creation result with created/skipped counts"},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Bulk create steam keys","tags":["Steam Keys"]}},"/api/v1/steam-keys/admin/{id}":{"get":{"description":"Admin-only endpoint to retrieve a single steam key by ID.","operationId":"SteamKeysController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/SteamKeyResponseDto"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Steam key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get a steam key by ID","tags":["Steam Keys"]},"patch":{"description":"Admin-only endpoint to update a steam key. Can assign or unassign a user.","operationId":"SteamKeysController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSteamKeyRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/SteamKeyResponseDto"}}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Steam key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update a steam key","tags":["Steam Keys"]},"delete":{"description":"Admin-only endpoint to delete a steam key by ID.","operationId":"SteamKeysController_delete","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Steam key deleted successfully"},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Steam key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Delete a steam key","tags":["Steam Keys"]}},"/api/v1/patchkit-keys/me":{"get":{"description":"Returns the patchkit key assigned to the authenticated user, or null if none is assigned.","operationId":"PatchkitKeysController_getMyKey","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PatchkitKeyResponseDto"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get my patchkit key","tags":["Patchkit Keys"]}},"/api/v1/patchkit-keys/claim":{"post":{"description":"Claim an unassigned patchkit key by providing the key value. The key must exist and be unassigned.","operationId":"PatchkitKeysController_claimKey","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimPatchkitKeyRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PatchkitKeyResponseDto"}}}}}},"400":{"description":"Patchkit key has already been claimed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Patchkit key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Claim a patchkit key","tags":["Patchkit Keys"]}},"/api/v1/patchkit-keys/admin":{"post":{"description":"Admin-only endpoint to create a single patchkit key.","operationId":"PatchkitKeysController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePatchkitKeyRequestDto"}}}},"responses":{"201":{"description":"Patchkit key created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchkitKeyResponseDto"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Patchkit key already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Create a new patchkit key","tags":["Patchkit Keys"]},"get":{"description":"Admin-only endpoint to retrieve all patchkit keys with filtering options including assigned status, user, and key search. Supports pagination.","operationId":"PatchkitKeysController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"userId","required":false,"in":"query","description":"Filter by assigned user ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"username","required":false,"in":"query","description":"Filter by assigned username (partial match, case-insensitive)","schema":{"example":"john_doe","type":"string"}},{"name":"isAssigned","required":false,"in":"query","description":"Filter by assigned status (true = assigned, false = unassigned)","schema":{"example":false,"type":"boolean"}},{"name":"key","required":false,"in":"query","description":"Search by key value (partial match, case-insensitive)","schema":{"example":"XXXXX","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PatchkitKeyResponseDto"}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get all patchkit keys with filters","tags":["Patchkit Keys"]}},"/api/v1/patchkit-keys/admin/bulk":{"post":{"description":"Admin-only endpoint to create multiple patchkit keys. Skips duplicates and returns count of created/skipped keys.","operationId":"PatchkitKeysController_bulkCreate","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCreatePatchkitKeysRequestDto"}}}},"responses":{"201":{"description":"Bulk creation result with created/skipped counts"},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Bulk create patchkit keys","tags":["Patchkit Keys"]}},"/api/v1/patchkit-keys/admin/{id}":{"get":{"description":"Admin-only endpoint to retrieve a single patchkit key by ID.","operationId":"PatchkitKeysController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PatchkitKeyResponseDto"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Patchkit key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get a patchkit key by ID","tags":["Patchkit Keys"]},"patch":{"description":"Admin-only endpoint to update a patchkit key. Can assign or unassign a user.","operationId":"PatchkitKeysController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePatchkitKeyRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PatchkitKeyResponseDto"}}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Patchkit key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update a patchkit key","tags":["Patchkit Keys"]},"delete":{"description":"Admin-only endpoint to delete a patchkit key by ID.","operationId":"PatchkitKeysController_delete","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Patchkit key deleted successfully"},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Patchkit key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Delete a patchkit key","tags":["Patchkit Keys"]}},"/api/v1/servers":{"post":{"operationId":"ServersController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateServerRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CreateServerResponseDto"}}}}}},"400":{"description":"The request body is invalid."},"401":{"description":"Unauthorized."},"404":{"description":"Map not found."},"409":{"description":"Server slug already exists."},"500":{"description":"Failed to create server."}},"security":[{"bearer":[]}],"summary":"Create a new server.","tags":["Servers"]},"get":{"operationId":"ServersController_retrieveAll","parameters":[{"name":"name","required":false,"in":"query","description":"The name of the server to search for.","schema":{"type":"string"}},{"name":"slug","required":false,"in":"query","description":"The slug of the server to search for.","schema":{"type":"string"}},{"name":"ownerId","required":false,"in":"query","description":"The ID of the owner to search for.","schema":{"type":"string"}},{"name":"gameMode","required":false,"in":"query","description":"The game mode to search for.","schema":{"type":"array","items":{"type":"string","enum":["Sandbox","Roleplay","Survival","Free For All","Team Deathmatch","Capture The Flag","Social"]}}},{"name":"hostingType","required":false,"in":"query","description":"The hosting type to search for.","schema":{"type":"array","items":{"type":"string","enum":["Dedicated","Local","Provisioned"]}}},{"name":"contentRating","required":false,"in":"query","description":"The content rating to search for.","schema":{"type":"array","items":{"type":"string","enum":["Everyone","Teen","Mature","Adult"]}}},{"name":"tags","required":false,"in":"query","description":"The tags to search for.","schema":{"type":"array","items":{"type":"string"}}},{"name":"publishedAfter","required":false,"in":"query","description":"The date to search for servers published after.","schema":{"format":"date-time","type":"string"}},{"name":"publishedBefore","required":false,"in":"query","description":"The date to search for servers published before.","schema":{"format":"date-time","type":"string"}},{"name":"updatedAfter","required":false,"in":"query","description":"The date to search for servers updated after.","schema":{"format":"date-time","type":"string"}},{"name":"updatedBefore","required":false,"in":"query","description":"The date to search for servers updated before.","schema":{"format":"date-time","type":"string"}},{"name":"packageId","required":false,"in":"query","description":"The package ID to search for servers that use any version of this package.","schema":{"type":"string"}},{"name":"packageVersionId","required":false,"in":"query","description":"The package version ID to search for servers that use this specific package version (either as worldId or in packageVersions).","schema":{"type":"string"}},{"name":"showOnlyPrivate","required":false,"in":"query","description":"Show only private servers that the authenticated user has access to (either as owner or whitelisted). Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"hideMine","required":false,"in":"query","description":"Hide servers owned by the authenticated user. Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by.","schema":{"type":"string","enum":["name","slug","currentPlayers","visits","createdAt","updatedAt","publishedAt"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in.","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of servers to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServerResponseDto"}}}}}}},"400":{"description":"The request body is invalid."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Retrieve all servers.","tags":["Servers"]}},"/api/v1/servers/{serverId}/getnewtoken":{"post":{"operationId":"ServersController_getNewToken","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/ServerTokenResponseDto"}}}}}},"401":{"description":"Unauthorized."},"403":{"description":"The current user is not the owner of the server."},"404":{"description":"Server not found."}},"security":[{"bearer":[]}],"summary":"Generate a new 6-month server token.","tags":["Servers"]}},"/api/v1/servers/{serverId}/restart":{"post":{"operationId":"ServersController_restartServer","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"force","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Server restarted successfully."},"400":{"description":"Server is currently updating. Use force=true to override."},"401":{"description":"Unauthorized."},"403":{"description":"Not the server owner or server is not provisioned."},"404":{"description":"Server not found."}},"security":[{"bearer":[]}],"summary":"Restart a provisioned server's Docker containers.","tags":["Servers"]}},"/api/v1/servers/{serverId}/update":{"post":{"operationId":"ServersController_updateServer","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Server update initiated."},"400":{"description":"Server cannot be updated in its current state."},"401":{"description":"Unauthorized."},"403":{"description":"Not the server owner or server is not provisioned."},"404":{"description":"Server not found."}},"security":[{"bearer":[]}],"summary":"Trigger a manual update on a provisioned server (pull latest image and recreate).","tags":["Servers"]}},"/api/v1/servers/{serverId}/wipe":{"post":{"operationId":"ServersController_wipeServer","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Server wipe initiated."},"400":{"description":"Server cannot be wiped in its current state."},"401":{"description":"Unauthorized."},"403":{"description":"Not the server owner or server is not provisioned."},"404":{"description":"Server not found."}},"security":[{"bearer":[]}],"summary":"Wipe a provisioned server's persistent data (world content, saves, persistent state) and restart it.","tags":["Servers"]}},"/api/v1/servers/me":{"get":{"operationId":"ServersController_retrieveMine","parameters":[{"name":"name","required":false,"in":"query","description":"The name of the server to search for.","schema":{"type":"string"}},{"name":"slug","required":false,"in":"query","description":"The slug of the server to search for.","schema":{"type":"string"}},{"name":"ownerId","required":false,"in":"query","description":"The ID of the owner to search for.","schema":{"type":"string"}},{"name":"gameMode","required":false,"in":"query","description":"The game mode to search for.","schema":{"type":"array","items":{"type":"string","enum":["Sandbox","Roleplay","Survival","Free For All","Team Deathmatch","Capture The Flag","Social"]}}},{"name":"hostingType","required":false,"in":"query","description":"The hosting type to search for.","schema":{"type":"array","items":{"type":"string","enum":["Dedicated","Local","Provisioned"]}}},{"name":"contentRating","required":false,"in":"query","description":"The content rating to search for.","schema":{"type":"array","items":{"type":"string","enum":["Everyone","Teen","Mature","Adult"]}}},{"name":"tags","required":false,"in":"query","description":"The tags to search for.","schema":{"type":"array","items":{"type":"string"}}},{"name":"publishedAfter","required":false,"in":"query","description":"The date to search for servers published after.","schema":{"format":"date-time","type":"string"}},{"name":"publishedBefore","required":false,"in":"query","description":"The date to search for servers published before.","schema":{"format":"date-time","type":"string"}},{"name":"updatedAfter","required":false,"in":"query","description":"The date to search for servers updated after.","schema":{"format":"date-time","type":"string"}},{"name":"updatedBefore","required":false,"in":"query","description":"The date to search for servers updated before.","schema":{"format":"date-time","type":"string"}},{"name":"packageId","required":false,"in":"query","description":"The package ID to search for servers that use any version of this package.","schema":{"type":"string"}},{"name":"packageVersionId","required":false,"in":"query","description":"The package version ID to search for servers that use this specific package version (either as worldId or in packageVersions).","schema":{"type":"string"}},{"name":"showOnlyPrivate","required":false,"in":"query","description":"Show only private servers that the authenticated user has access to (either as owner or whitelisted). Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"hideMine","required":false,"in":"query","description":"Hide servers owned by the authenticated user. Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by.","schema":{"type":"string","enum":["name","slug","currentPlayers","visits","createdAt","updatedAt","publishedAt"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in.","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of servers to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServerResponseDto"}}}}}}},"400":{"description":"The request body is invalid."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Retrieve all servers owned by the current user.","tags":["Servers"]}},"/api/v1/servers/{serverId}":{"get":{"operationId":"ServersController_retrieveOne","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/ServerResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"Server not found."}},"security":[{"bearer":[]}],"summary":"Retrieve a server by ID.","tags":["Servers"]},"patch":{"operationId":"ServersController_update","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateServerRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UpdateServerResponseDto"}}}}}},"400":{"description":"Failed to update server."},"401":{"description":"Unauthorized."},"403":{"description":"The current user is not the owner of the server."},"404":{"description":"Server not found."}},"security":[{"bearer":[]}],"summary":"Update a server by ID.","tags":["Servers"]},"delete":{"operationId":"ServersController_remove","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The server has been deleted."},"400":{"description":"Failed to delete server."},"401":{"description":"Unauthorized."},"403":{"description":"The current user is not the owner of the server."},"404":{"description":"The server was not found."}},"security":[{"bearer":[]}],"summary":"Delete a server by ID.","tags":["Servers"]}},"/api/v1/servers/{serverId}/kicks":{"post":{"operationId":"ServersController_kickUser","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerateUserRequestDto"}}}},"responses":{"200":{"description":"Player kicked."},"401":{"description":"Unauthorized."},"409":{"description":"Player is already kicked. Use PATCH to update."}},"security":[{"bearer":[]}],"summary":"Kick a player from the server for a duration.","tags":["Servers"]},"get":{"operationId":"ServersController_listKicked","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"List of kicked players."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"List kicked players for a server.","tags":["Servers"]}},"/api/v1/servers/{serverId}/kicks/{userId}":{"delete":{"operationId":"ServersController_unkickUser","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Player un-kicked."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Remove a player from kicked list.","tags":["Servers"]},"patch":{"operationId":"ServersController_updateKick","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateModerationRequestDto"}}}},"responses":{"200":{"description":"Kick updated successfully."},"401":{"description":"Unauthorized."},"403":{"description":"The current user is not the owner of the server."},"404":{"description":"Server or kick not found."}},"security":[{"bearer":[]}],"summary":"Update kick duration and/or reason for a player.","tags":["Servers"]}},"/api/v1/servers/{serverId}/bans":{"post":{"operationId":"ServersController_banUser","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerateUserRequestDto"}}}},"responses":{"200":{"description":"Player banned."},"401":{"description":"Unauthorized."},"409":{"description":"Player is already banned. Use PATCH to update."}},"security":[{"bearer":[]}],"summary":"Ban a player from the server for a duration.","tags":["Servers"]},"get":{"operationId":"ServersController_listBanned","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"List of banned players."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"List banned players for a server.","tags":["Servers"]}},"/api/v1/servers/{serverId}/bans/{userId}":{"delete":{"operationId":"ServersController_unbanUser","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Player un-banned."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Remove a player from banned list.","tags":["Servers"]},"patch":{"operationId":"ServersController_updateBan","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateModerationRequestDto"}}}},"responses":{"200":{"description":"Ban updated successfully."},"401":{"description":"Unauthorized."},"403":{"description":"The current user is not the owner of the server."},"404":{"description":"Server or ban not found."}},"security":[{"bearer":[]}],"summary":"Update ban duration and/or reason for a player.","tags":["Servers"]}},"/api/v1/servers/{serverId}/secret":{"post":{"deprecated":true,"operationId":"ServersController_createNewSecret","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/ServerWithSecretResponseDto"}}}}}},"401":{"description":"Unauthorized."},"403":{"description":"The current user is not the owner of the server."},"404":{"description":"Server not found."},"500":{"description":"Failed to create new server secret."}},"security":[{"bearer":[]}],"summary":"Create a new secret for a server.","tags":["Servers"]}},"/api/v1/servers/{serverId}/publish":{"post":{"operationId":"ServersController_publish","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/ServerResponseDto"}}}}}},"400":{"description":"Server is already published."},"401":{"description":"Unauthorized."},"403":{"description":"The current user is not the owner of the server."},"404":{"description":"Server not found."},"500":{"description":"Failed to publish server."}},"security":[{"bearer":[]}],"summary":"Publish a server.","tags":["Servers"]}},"/api/v1/servers/{serverId}/unpublish":{"post":{"operationId":"ServersController_unpublish","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/ServerResponseDto"}}}}}},"400":{"description":"Server is not published."},"401":{"description":"Unauthorized."},"403":{"description":"The current user is not the owner of the server."},"404":{"description":"Server not found."},"500":{"description":"Failed to unpublish server."}},"security":[{"bearer":[]}],"summary":"Unpublish a server.","tags":["Servers"]}},"/api/v1/servers/admin/transfer-ownership":{"post":{"description":"Client tokens are not allowed on this route: This route is not supported for security reasons.\n\nAdmin access is required to access this route.","operationId":"ServersController_transferOwnership","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferServerOwnershipRequestDto"}}}},"responses":{"200":{"description":"Ownership transferred."},"400":{"description":"Invalid payload."},"401":{"description":"Unauthorized."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"One or more servers not found."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Admin: Transfer server ownership.","tags":["Servers","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported for security reasons."}}},"/api/v1/server-status/{serverId}":{"patch":{"operationId":"ServerStatusController_update","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateServerStatusRequestDto"}}}},"responses":{"200":{"description":"The server status has been updated."},"400":{"description":"Failed to update server status."},"403":{"description":"You are not allowed to update this server."},"404":{"description":"Server not found."}},"summary":"Update the status of a server.","tags":["ServerStatus"]}},"/api/v1/servers/{serverId}/logs":{"get":{"description":"Opens a Server-Sent Events stream of Docker Compose logs. Authentication is via the `token` query parameter (JWT access token). Only the server owner can access logs.","operationId":"ServerLogsController_streamLogs","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"token","required":true,"in":"query","description":"JWT access token for SSE authentication","schema":{"type":"string"}},{"name":"tail","required":false,"in":"query","description":"Number of historical log lines to return before streaming","schema":{"minimum":1,"maximum":10000,"default":200,"type":"number"}},{"name":"container","required":false,"in":"query","description":"Optional Docker container name to filter logs","schema":{"example":"helix-server","type":"string"}}],"responses":{"200":{"description":"SSE stream of log lines."},"400":{"description":"Server has no IP address."},"401":{"description":"Invalid or missing token."},"403":{"description":"Not the server owner or not provisioned."},"404":{"description":"Server not found."}},"summary":"Stream Docker logs from a provisioned server (SSE)","tags":["Server Logs"]}},"/api/v1/servers/{serverId}/logs/download":{"get":{"description":"Downloads the complete Docker Compose logs (full lifetime) as a text file. Authentication is via the `token` query parameter (JWT access token). Only the server owner can download logs.","operationId":"ServerLogsController_downloadLogs","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"token","required":true,"in":"query","description":"JWT access token","schema":{"type":"string"}},{"name":"container","required":false,"in":"query","description":"Optional Docker container name to filter logs","schema":{}}],"responses":{"200":{"description":"Full log file download."},"400":{"description":"Server has no IP address."},"401":{"description":"Invalid or missing token."},"403":{"description":"Not the server owner or not provisioned."},"404":{"description":"Server not found."}},"summary":"Download full Docker logs from a provisioned server","tags":["Server Logs"]}},"/api/v1/servers/{serverId}/groups":{"get":{"operationId":"ServerPermissionsController_listGroups","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServerPermissionGroupResponseDto"}}}}}}},"401":{"description":"Unauthorized."},"403":{"description":"Not allowed to access this server."},"404":{"description":"Server not found."}},"security":[{"bearer":[]}],"summary":"List all permission groups for a server.","tags":["ServerPermissions"]},"post":{"operationId":"ServerPermissionsController_createGroup","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateServerPermissionGroupRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/ServerPermissionGroupResponseDto"}}}}}},"401":{"description":"Unauthorized."},"403":{"description":"Not allowed to access this server."},"404":{"description":"Server not found."},"409":{"description":"A group with this name already exists for this server."}},"security":[{"bearer":[]}],"summary":"Create a new permission group for a server.","tags":["ServerPermissions"]}},"/api/v1/servers/{serverId}/assignments":{"get":{"operationId":"ServerPermissionsController_listAssignments","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServerUserGroupAssignmentResponseDto"}}}}}}},"401":{"description":"Unauthorized."},"403":{"description":"Not allowed to access this server."},"404":{"description":"Server not found."}},"security":[{"bearer":[]}],"summary":"List all user-to-group assignments for a server.","tags":["ServerPermissions"]}},"/api/v1/servers/{serverId}/groups/{groupId}":{"patch":{"operationId":"ServerPermissionsController_updateGroup","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"groupId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateServerPermissionGroupRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/ServerPermissionGroupResponseDto"}}}}}},"400":{"description":"At least one updatable field must be provided."},"401":{"description":"Unauthorized."},"403":{"description":"Not allowed to access this server."},"404":{"description":"Server or group not found."},"409":{"description":"A group with this name already exists for this server."}},"security":[{"bearer":[]}],"summary":"Update an existing permission group.","tags":["ServerPermissions"]},"delete":{"operationId":"ServerPermissionsController_deleteGroup","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"groupId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/OkResponseDto"}}}}}},"401":{"description":"Unauthorized."},"403":{"description":"Not allowed to access this server."},"404":{"description":"Server or group not found."}},"security":[{"bearer":[]}],"summary":"Delete a permission group from a server.","tags":["ServerPermissions"]}},"/api/v1/servers/{serverId}/users/{userId}/group":{"get":{"operationId":"ServerPermissionsController_getUserGroup","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/ServerUserGroupAssignmentResponseDto"}}}}}},"401":{"description":"Unauthorized."},"403":{"description":"Not allowed to access this server."},"404":{"description":"Server or assignment not found."}},"security":[{"bearer":[]}],"summary":"Get the permission group assigned to a user on a server.","tags":["ServerPermissions"]},"post":{"operationId":"ServerPermissionsController_assignUserGroup","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignServerUserGroupRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/ServerUserGroupAssignmentResponseDto"}}}}}},"401":{"description":"Unauthorized."},"403":{"description":"Not allowed to access this server."},"404":{"description":"Server, user, or group not found."}},"security":[{"bearer":[]}],"summary":"Assign a user to a permission group on a server.","tags":["ServerPermissions"]},"delete":{"operationId":"ServerPermissionsController_removeUserGroup","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/OkResponseDto"}}}}}},"401":{"description":"Unauthorized."},"403":{"description":"Not allowed to access this server."},"404":{"description":"Server or assignment not found."}},"security":[{"bearer":[]}],"summary":"Remove a user group assignment from a server.","tags":["ServerPermissions"]}},"/api/v1/servers/admin/all":{"get":{"description":"Returns all servers regardless of owner, privacy, published or online state. Supports filtering by name, owner, status, hosting type, region and moderation status.","operationId":"AdminServersController_listAll","parameters":[{"name":"name","required":false,"in":"query","description":"Partial, case-insensitive server name match.","schema":{"type":"string"}},{"name":"ownerId","required":false,"in":"query","description":"Filter by owner user ID.","schema":{"type":"string"}},{"name":"ownerUsername","required":false,"in":"query","description":"Partial, case-insensitive owner username match.","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by server status.","schema":{"type":"string","enum":["Offline","Starting","Stopping","Online","Updating","Error"]}},{"name":"hostingType","required":false,"in":"query","description":"Filter by hosting type.","schema":{"type":"string","enum":["Dedicated","Local","Provisioned"]}},{"name":"moderationStatus","required":false,"in":"query","description":"Filter by moderation status.","schema":{"type":"string","enum":["Active","Suspended","TakenDown"]}},{"name":"region","required":false,"in":"query","description":"Filter by region (2-letter ISO code).","schema":{"type":"string"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by.","schema":{"type":"string","enum":["name","slug","visits","createdAt","updatedAt","publishedAt"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in.","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Servers per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminServerResponseDto"}}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[ADMIN] List every server across all users.","tags":["No Client Token Support","Servers Admin"]}},"/api/v1/servers/admin/audit-log":{"get":{"operationId":"AdminServersController_listGlobalAuditLog","parameters":[{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServerAuditLogResponseDto"}}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[ADMIN] List recent server moderation/admin actions.","tags":["No Client Token Support","Servers Admin"]}},"/api/v1/servers/admin/{serverId}/audit-log":{"get":{"operationId":"AdminServersController_listServerAuditLog","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServerAuditLogResponseDto"}}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[ADMIN] List admin actions for a single server.","tags":["No Client Token Support","Servers Admin"]}},"/api/v1/servers/admin/{serverId}":{"get":{"operationId":"AdminServersController_getOne","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/AdminServerResponseDto"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Server not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get any server by ID (bypasses privacy).","tags":["No Client Token Support","Servers Admin"]},"patch":{"operationId":"AdminServersController_update","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateServerRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/AdminServerResponseDto"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Server not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update any server.","tags":["No Client Token Support","Servers Admin"]},"delete":{"operationId":"AdminServersController_remove","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The server has been deleted."},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Server not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[ADMIN] Delete any server.","tags":["No Client Token Support","Servers Admin"]}},"/api/v1/servers/admin/{serverId}/confirm-media":{"post":{"description":"Call this AFTER uploading server preview/thumbnail images via the presigned URLs. Each uploaded object is re-fetched from R2 and run through the shared moderation gate; a rejected object is deleted and the request fails with 422.","operationId":"AdminServersController_confirmMedia","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmServerMediaRequestDto"}}}},"responses":{"200":{"description":"All uploaded media passed moderation."},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Server not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."},"422":{"description":"An uploaded object was rejected by moderation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Confirm & moderate uploaded server media.","tags":["No Client Token Support","Servers Admin"]}},"/api/v1/servers/admin/{serverId}/restart":{"post":{"operationId":"AdminServersController_restart","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"force","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Server restarted."},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[ADMIN] Restart any provisioned server.","tags":["No Client Token Support","Servers Admin"]}},"/api/v1/servers/admin/{serverId}/update":{"post":{"operationId":"AdminServersController_triggerUpdate","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Server update initiated."},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[ADMIN] Trigger an update on any provisioned server.","tags":["No Client Token Support","Servers Admin"]}},"/api/v1/servers/admin/{serverId}/wipe":{"post":{"operationId":"AdminServersController_wipe","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Server wipe initiated."},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[ADMIN] Wipe any provisioned server's persistent data and restart it.","tags":["No Client Token Support","Servers Admin"]}},"/api/v1/servers/admin/{serverId}/suspend":{"post":{"operationId":"AdminServersController_suspend","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerateServerRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/AdminServerResponseDto"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[ADMIN] Suspend a server (forces it offline).","tags":["No Client Token Support","Servers Admin"]}},"/api/v1/servers/admin/{serverId}/unsuspend":{"post":{"operationId":"AdminServersController_unsuspend","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerateServerRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/AdminServerResponseDto"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[ADMIN] Lift a suspension (restores to Active).","tags":["No Client Token Support","Servers Admin"]}},"/api/v1/servers/admin/{serverId}/takedown":{"post":{"operationId":"AdminServersController_takedown","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerateServerRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/AdminServerResponseDto"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[ADMIN] Take down a server (forces it offline and private).","tags":["No Client Token Support","Servers Admin"]}},"/api/v1/servers/admin/{serverId}/restore":{"post":{"operationId":"AdminServersController_restore","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerateServerRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/AdminServerResponseDto"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[ADMIN] Restore a moderated server to Active.","tags":["No Client Token Support","Servers Admin"]}},"/api/v1/servers/admin/{serverId}/notify-owner":{"post":{"operationId":"AdminServersController_notifyOwner","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotifyOwnerRequestDto"}}}},"responses":{"200":{"description":"Notification sent."},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"[ADMIN] Send an in-app notification to the server's owner.","tags":["No Client Token Support","Servers Admin"]}},"/api/v1/packages":{"post":{"operationId":"PackagesController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePackageRequestDto"},"examples":{"filesArrayPreferred":{"summary":"Preferred: files[] in initial version","value":{"name":"My Package","slug":"my-package","description":"This is a description of my package.","type":"Map","contentRating":"Everyone","isPrivate":false,"previewKeys":["Preview_1"],"tags":["Sandbox"],"priceLix":0,"version":{"files":[{"key":"client","size":37434163,"metadata":{}},{"key":"metadata","size":1024,"metadata":{"format":"json"}}],"releaseNotes":"Initial release","dependencyIds":[],"config":{}}}},"legacyCompatible":{"summary":"Backward compatible: legacy size fields in initial version","value":{"name":"My Package","slug":"my-package","description":"This is a description of my package.","type":"Map","contentRating":"Everyone","isPrivate":false,"version":{"clientSize":37434163,"serverSize":0,"editorSize":0,"metadataSize":1024,"releaseNotes":"Initial release","dependencyIds":[],"config":{}}}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CreatePackageResponseDto"}}}}}},"400":{"description":"The request body is invalid."},"401":{"description":"Unauthorized."},"409":{"description":"Package slug already exists."},"500":{"description":"Failed to create package."}},"security":[{"bearer":[]}],"summary":"Create a new package.","tags":["Packages"]},"get":{"operationId":"PackagesController_retrieveAll","parameters":[{"name":"name","required":false,"in":"query","description":"The name of the package to search for.","schema":{"type":"string"}},{"name":"slug","required":false,"in":"query","description":"The slug of the package to search for.","schema":{"type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"The ID of the creator to search for.","schema":{"type":"string"}},{"name":"showOnlyPrivate","required":false,"in":"query","description":"Show only private packages that the authenticated user has access to (either as owner or via role-granted access). Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"hideMine","required":false,"in":"query","description":"Hide packages created by the authenticated user. Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"type","required":false,"in":"query","description":"The package types to search for.","schema":{"type":"array","items":{"type":"string","enum":["World","Map","QRE","Vehicle","Character","Character Preset","Weapon","Wearable","Animation","Structure","Interior","Tool","Effect","Sound","Script","Addon","EDL","Other"]}}},{"name":"excludeType","required":false,"in":"query","description":"The package types to exclude from the search.","schema":{"type":"array","items":{"type":"string","enum":["World","Map","QRE","Vehicle","Character","Character Preset","Weapon","Wearable","Animation","Structure","Interior","Tool","Effect","Sound","Script","Addon","EDL","Other"]}}},{"name":"contentRating","required":false,"in":"query","description":"The content rating of the package to search for.","schema":{"type":"string","enum":["Everyone","Teen","Mature","Adult"]}},{"name":"tags","required":false,"in":"query","description":"The tags of the package to search for.","schema":{"type":"array","items":{"type":"string"}}},{"name":"publishedAfter","required":false,"in":"query","description":"The date to search for packages published after.","schema":{"format":"date-time","type":"string"}},{"name":"publishedBefore","required":false,"in":"query","description":"The date to search for packages published before.","schema":{"format":"date-time","type":"string"}},{"name":"updatedAfter","required":false,"in":"query","description":"The date to search for packages updated after.","schema":{"format":"date-time","type":"string"}},{"name":"updatedBefore","required":false,"in":"query","description":"The date to search for packages updated before.","schema":{"format":"date-time","type":"string"}},{"name":"lastReleaseAfter","required":false,"in":"query","description":"The date to search for packages with latest release after this date.","schema":{"format":"date-time","type":"string"}},{"name":"lastReleaseBefore","required":false,"in":"query","description":"The date to search for packages with latest release before this date.","schema":{"format":"date-time","type":"string"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by.","schema":{"type":"string","enum":["name","slug","createdAt","updatedAt","publishedAt","lastReleaseAt"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in.","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of servers to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PackageCollectionWithUserScoreResponseDto"}}}}}}},"400":{"description":"The request body is invalid."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get all packages.","tags":["Packages"]}},"/api/v1/packages/me":{"get":{"operationId":"PackagesController_retrieveMine","parameters":[{"name":"name","required":false,"in":"query","description":"The name of the package to search for.","schema":{"type":"string"}},{"name":"slug","required":false,"in":"query","description":"The slug of the package to search for.","schema":{"type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"The ID of the creator to search for.","schema":{"type":"string"}},{"name":"showOnlyPrivate","required":false,"in":"query","description":"Show only private packages that the authenticated user has access to (either as owner or via role-granted access). Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"hideMine","required":false,"in":"query","description":"Hide packages created by the authenticated user. Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"type","required":false,"in":"query","description":"The package types to search for.","schema":{"type":"array","items":{"type":"string","enum":["World","Map","QRE","Vehicle","Character","Character Preset","Weapon","Wearable","Animation","Structure","Interior","Tool","Effect","Sound","Script","Addon","EDL","Other"]}}},{"name":"excludeType","required":false,"in":"query","description":"The package types to exclude from the search.","schema":{"type":"array","items":{"type":"string","enum":["World","Map","QRE","Vehicle","Character","Character Preset","Weapon","Wearable","Animation","Structure","Interior","Tool","Effect","Sound","Script","Addon","EDL","Other"]}}},{"name":"contentRating","required":false,"in":"query","description":"The content rating of the package to search for.","schema":{"type":"string","enum":["Everyone","Teen","Mature","Adult"]}},{"name":"tags","required":false,"in":"query","description":"The tags of the package to search for.","schema":{"type":"array","items":{"type":"string"}}},{"name":"publishedAfter","required":false,"in":"query","description":"The date to search for packages published after.","schema":{"format":"date-time","type":"string"}},{"name":"publishedBefore","required":false,"in":"query","description":"The date to search for packages published before.","schema":{"format":"date-time","type":"string"}},{"name":"updatedAfter","required":false,"in":"query","description":"The date to search for packages updated after.","schema":{"format":"date-time","type":"string"}},{"name":"updatedBefore","required":false,"in":"query","description":"The date to search for packages updated before.","schema":{"format":"date-time","type":"string"}},{"name":"lastReleaseAfter","required":false,"in":"query","description":"The date to search for packages with latest release after this date.","schema":{"format":"date-time","type":"string"}},{"name":"lastReleaseBefore","required":false,"in":"query","description":"The date to search for packages with latest release before this date.","schema":{"format":"date-time","type":"string"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by.","schema":{"type":"string","enum":["name","slug","createdAt","updatedAt","publishedAt","lastReleaseAt"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in.","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of servers to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PackageCollectionWithUserScoreResponseDto"}}}}}}},"400":{"description":"The request body is invalid."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get all packages created by the current user.","tags":["Packages"]}},"/api/v1/packages/{packageId}":{"get":{"operationId":"PackagesController_retrieveOne","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PackageWithUserScoreResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"Package not found."}},"security":[{"bearer":[]}],"summary":"Get a package by ID.","tags":["Packages"]},"patch":{"operationId":"PackagesController_update","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePackageRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UpdatePackageResponseDto"}}}}}},"400":{"description":"Failed to update package."},"401":{"description":"Unauthorized."},"403":{"description":"The current user is not the creator of the package."},"404":{"description":"The package was not found."},"500":{"description":"Failed to update package."}},"security":[{"bearer":[]}],"summary":"Update a package by ID.","tags":["Packages"]},"put":{"deprecated":true,"operationId":"PackagesController_updatePut","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePackageRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UpdatePackageResponseDto"}}}}}},"400":{"description":"Failed to update package."},"401":{"description":"Unauthorized."},"403":{"description":"The current user is not the creator of the package."},"404":{"description":"The package was not found."}},"security":[{"bearer":[]}],"summary":"Update a package by ID.","tags":["Packages"]},"delete":{"description":"Client tokens are not allowed on this route: This route is not supported at this time.","operationId":"PackagesController_delete","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The package has been deleted."},"401":{"description":"Unauthorized."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"The package was not found."},"406":{"description":"Client token version is outdated."},"500":{"description":"Failed to delete package."}},"security":[{"bearer":[]}],"summary":"Delete a package by ID.","tags":["Packages","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported at this time."}}},"/api/v1/packages/{packageId}/version-health":{"get":{"operationId":"PackagesController_retrieveLatestVersionHealth","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PackageVersionHealthResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"Package not found."}},"security":[{"bearer":[]}],"summary":"Check dependency health for the latest version of a package.","tags":["Packages"]}},"/api/v1/packages/{packageId}/reviews":{"get":{"description":"Returns a paginated list of user reviews for the specified package, including thumbs up percentage. If authenticated, also includes all reviews for this package by the requesting user in a separate field. This endpoint replaces the deprecated /api/v1/user-reviews/package/:packageId.","operationId":"PackagesController_getPackageReviews","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Limit (items per page)","schema":{"default":10,"example":10,"type":"number"}}],"responses":{"200":{"description":"Paginated user reviews for the package.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserReviewsWithThumbsResponseDto"}}}},"400":{"description":"Invalid packageId format. Must be a valid UUID."},"401":{"description":"Unauthorized."},"404":{"description":"Package not found."}},"security":[{"bearer":[]}],"summary":"Get all user reviews for a package (paginated).","tags":["Packages"]}},"/api/v1/packages/{packageId}/latest-version":{"patch":{"description":"Updates the latest version of a package without requiring the packageVersionId. The endpoint automatically identifies and updates the most recent version.","operationId":"PackagesController_updateLatestVersion","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePackageVersionRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UpdatePackageVersionResponseDto"}}}}}},"400":{"description":"Failed to update package version."},"401":{"description":"Unauthorized."},"403":{"description":"The current user is not the creator of the package."},"404":{"description":"The package was not found."}},"security":[{"bearer":[]}],"summary":"Update the latest version of a package.","tags":["Packages"]}},"/api/v1/packages/{packageId}/record-download":{"post":{"operationId":"PackagesController_recordDownload","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Request received."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]},{"shared_secret":[]}],"summary":"Record a download of a package.","tags":["Packages"]}},"/api/v1/packages/admin/transfer-ownership":{"post":{"description":"Client tokens are not allowed on this route: This route is not supported for security reasons.\n\nAdmin access is required to access this route.","operationId":"PackagesController_transferOwnership","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferOwnershipRequestDto"}}}},"responses":{"200":{"description":"Ownership transferred."},"400":{"description":"Invalid payload."},"401":{"description":"Unauthorized."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"One or more packages not found."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Admin: Transfer package ownership.","tags":["Packages","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported for security reasons."}}},"/api/v1/package-versions":{"post":{"operationId":"PackageVersionsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePackageVersionRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CreatePackageVersionResponseDto"}}}}}},"400":{"description":"Package version dependencies are invalid."},"401":{"description":"Unauthorized."},"404":{"description":"Package not found."},"500":{"description":"Failed to create package version."}},"security":[{"bearer":[]}],"summary":"Create a package version.","tags":["PackageVersions"]},"get":{"operationId":"PackageVersionsController_retrieveAll","parameters":[{"name":"ids","required":false,"in":"query","description":"The IDs of the package versions to search for.","schema":{"type":"array","items":{"type":"string"}}},{"name":"creatorId","required":false,"in":"query","description":"The ID of the creator to search for.","schema":{"type":"string"}},{"name":"packageId","required":false,"in":"query","description":"The owning package ID of the package versions to search for.","schema":{"type":"string"}},{"name":"revision","required":false,"in":"query","description":"The revision of the package version to search for.","schema":{"type":"number"}},{"name":"publishedAfter","required":false,"in":"query","description":"The date to search for package versions published after.","schema":{"format":"date-time","type":"string"}},{"name":"publishedBefore","required":false,"in":"query","description":"The date to search for package versions published before.","schema":{"format":"date-time","type":"string"}},{"name":"updatedAfter","required":false,"in":"query","description":"The date to search for package versions updated after.","schema":{"format":"date-time","type":"string"}},{"name":"updatedBefore","required":false,"in":"query","description":"The date to search for package versions updated before.","schema":{"format":"date-time","type":"string"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by.","schema":{"type":"string","enum":["packageId","name","createdAt","updatedAt","publishedAt"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in.","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of servers to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PackageVersionResponseDto"}}}}}}},"400":{"description":"The request body is invalid."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Retrieve all package versions.","tags":["PackageVersions"]}},"/api/v1/package-versions/{packageVersionId}/uploads/complete":{"post":{"operationId":"PackageVersionsController_completeMultipart","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteMultipartUploadRequestDto"}}}},"responses":{"200":{"description":"Multipart upload completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteMultipartUploadResponseDto"}}}},"400":{"description":"Invalid completion request."},"401":{"description":"Unauthorized."},"404":{"description":"Package version not found."}},"security":[{"bearer":[]}],"summary":"Complete a multipart upload for a package version asset.","tags":["PackageVersions"]}},"/api/v1/package-versions/{packageVersionId}/uploads/complete-single":{"post":{"operationId":"PackageVersionsController_completeSingle","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteSingleUploadRequestDto"}}}},"responses":{"200":{"description":"Single-PUT upload confirmed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteSingleUploadResponseDto"}}}},"400":{"description":"Invalid completion request."},"401":{"description":"Unauthorized."},"404":{"description":"Package version not found."}},"security":[{"bearer":[]}],"summary":"Confirm a single-PUT (non-multipart) upload for a package version asset.","tags":["PackageVersions"]}},"/api/v1/package-versions/me":{"get":{"operationId":"PackageVersionsController_retrieveMine","parameters":[{"name":"ids","required":false,"in":"query","description":"The IDs of the package versions to search for.","schema":{"type":"array","items":{"type":"string"}}},{"name":"creatorId","required":false,"in":"query","description":"The ID of the creator to search for.","schema":{"type":"string"}},{"name":"packageId","required":false,"in":"query","description":"The owning package ID of the package versions to search for.","schema":{"type":"string"}},{"name":"revision","required":false,"in":"query","description":"The revision of the package version to search for.","schema":{"type":"number"}},{"name":"publishedAfter","required":false,"in":"query","description":"The date to search for package versions published after.","schema":{"format":"date-time","type":"string"}},{"name":"publishedBefore","required":false,"in":"query","description":"The date to search for package versions published before.","schema":{"format":"date-time","type":"string"}},{"name":"updatedAfter","required":false,"in":"query","description":"The date to search for package versions updated after.","schema":{"format":"date-time","type":"string"}},{"name":"updatedBefore","required":false,"in":"query","description":"The date to search for package versions updated before.","schema":{"format":"date-time","type":"string"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by.","schema":{"type":"string","enum":["packageId","name","createdAt","updatedAt","publishedAt"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in.","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of servers to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PackageVersionResponseDto"}}}}}}},"400":{"description":"The request body is invalid."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get all package versions created by the current user.","tags":["PackageVersions"]}},"/api/v1/package-versions/{packageVersionId}":{"get":{"operationId":"PackageVersionsController_retrieveOne","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PackageVersionResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"The package version was not found."}},"security":[{"bearer":[]}],"summary":"Retrieve a package version by ID.","tags":["PackageVersions"]},"patch":{"operationId":"PackageVersionsController_update","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePackageVersionRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UpdatePackageVersionResponseDto"}}}}}},"400":{"description":"Failed to update package version."},"401":{"description":"Unauthorized."},"403":{"description":"The current user is not the creator of the package."},"404":{"description":"The package version was not found."}},"security":[{"bearer":[]}],"summary":"Update a package version by ID.","tags":["PackageVersions"]},"put":{"deprecated":true,"operationId":"PackageVersionsController_updatePut","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePackageVersionRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UpdatePackageVersionResponseDto"}}}}}},"400":{"description":"Failed to update package version."},"401":{"description":"Unauthorized."},"403":{"description":"The current user is not the creator of the package."},"404":{"description":"The package version was not found."}},"security":[{"bearer":[]}],"summary":"Update a package version by ID.","tags":["PackageVersions"]},"delete":{"description":"Client tokens are not allowed on this route: This route is not supported at this time.","operationId":"PackageVersionsController_delete","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The package version has been deleted."},"401":{"description":"Unauthorized."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"The package version was not found."},"406":{"description":"Client token version is outdated."},"500":{"description":"Failed to delete package version."}},"security":[{"bearer":[]}],"summary":"Delete a package version by ID.","tags":["PackageVersions","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported at this time."}}},"/api/v1/package-versions/{packageVersionId}/health":{"get":{"operationId":"PackageVersionsController_retrieveHealth","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PackageVersionHealthResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"The package version was not found."}},"security":[{"bearer":[]}],"summary":"Check dependency health for a package version.","tags":["PackageVersions"]}},"/api/v1/package-versions/{packageVersionId}/keys":{"get":{"operationId":"PackageVersionsController_retrieveKeys","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PackageVersionKeysResponseDto"}}}}}},"401":{"description":"Unauthorized."},"403":{"description":"You do not have a license (grant) for this package."},"404":{"description":"The package version was not found, or has no encryption keys."}},"security":[{"bearer":[]}],"summary":"Retrieve decryption keys for an encrypted package version. Private packages: creator or an active PackageAccess grant only. Public packages: any authenticated user.","tags":["PackageVersions"]}},"/api/v1/package-versions/{packageVersionId}/assets":{"post":{"operationId":"PackageVersionAssetsController_createMany","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CreatePackageVersionAssetResponseDto"}}}}}}},"400":{"description":"The request body is invalid."},"401":{"description":"Unauthorized."},"404":{"description":"The package version was not found."}},"security":[{"bearer":[]}],"summary":"Creates multiple package version assets using the given array.","tags":["PackageVersionAssets"]},"get":{"operationId":"PackageVersionAssetsController_retrieveAll","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by.","schema":{"default":"index","type":"string","enum":["index","key","type"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of servers to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PackageVersionResponseDto"}}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"The package version was not found."}},"security":[{"bearer":[]}],"summary":"Retrieve all assets of a package version.","tags":["PackageVersionAssets"]},"put":{"operationId":"PackageVersionAssetsController_updateAll","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UpdatePackageVersionAssetResponseDto"}}}}}}},"400":{"description":"The request body is invalid."},"401":{"description":"Unauthorized."},"404":{"description":"The package version was not found."}},"security":[{"bearer":[]}],"summary":"Replaces all package version assets with the given array of assets.","tags":["PackageVersionAssets"]},"patch":{"operationId":"PackageVersionAssetsController_updateMany","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UpdatePackageVersionAssetResponseDto"}}}}}}},"400":{"description":"The request body is invalid."},"401":{"description":"Unauthorized."},"404":{"description":"The package version was not found."},"500":{"description":"Failed to update assets."}},"security":[{"bearer":[]}],"summary":"Updates existing package version assets specified by the given array of assets.","tags":["PackageVersionAssets"]},"delete":{"operationId":"PackageVersionAssetsController_deleteMany","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PackageVersionAssetResponseDto"}}}}}}},"400":{"description":"The request body is invalid."},"401":{"description":"Unauthorized."},"404":{"description":"The package version was not found."},"500":{"description":"Failed to delete assets."}},"security":[{"bearer":[]}],"summary":"Deletes package version assets specified by the given array of assets.","tags":["PackageVersionAssets"]}},"/api/v1/package-versions/{packageVersionId}/dependencies":{"get":{"operationId":"PackageVersionDependenciesController_retrieveAllDependencies","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}},{"name":"conflicts","required":false,"in":"query","description":"The strategy to use when resolving package version conflicts.","schema":{"default":"KeepLatest","type":"string","enum":["KeepAll","KeepLatest"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PackageVersionResponseDto"}}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"The package version was not found."}},"security":[{"bearer":[]}],"summary":"Retrieve all upstream dependencies of a package version.","tags":["PackageVersionDependencies"]}},"/api/v1/package-versions/{packageVersionId}/dependents":{"get":{"operationId":"PackageVersionDependenciesController_retrieveAllDependents","parameters":[{"name":"packageVersionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PackageVersionResponseDto"}}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"The package version was not found."}},"security":[{"bearer":[]}],"summary":"Retrieve all downstream dependents of a package version.","tags":["PackageVersionDependencies"]}},"/api/v1/package-access/{packageId}/batch-grant":{"post":{"description":"Bulk grant access to multiple users by providing either userIds or usernames. Returns detailed results for each user including success/failure status.","operationId":"PackageAccessController_batchGrant","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchGrantPackageAccessRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/BatchGrantPackageAccessResponseDto"}}}}}},"400":{"description":"Invalid request."},"403":{"description":"Only the package creator can perform this action."},"404":{"description":"Package not found."}},"security":[{"bearer":[]}],"summary":"Grant access-granted role to multiple users for a package (creator only).","tags":["PackageAccess"]}},"/api/v1/package-access/{packageId}/{userId}":{"post":{"operationId":"PackageAccessController_grant","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantPackageAccessRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PackageAccessResponseDto"}}}}}},"400":{"description":"Invalid request."},"403":{"description":"Only the package creator can perform this action."},"404":{"description":"Package or user not found."}},"security":[{"bearer":[]}],"summary":"Grant access-granted role to a user for a package (creator only).","tags":["PackageAccess"]},"patch":{"operationId":"PackageAccessController_update","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePackageAccessRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PackageAccessResponseDto"}}}}}},"400":{"description":"Invalid request."},"403":{"description":"Only the package creator can perform this action."},"404":{"description":"Grant not found."}},"security":[{"bearer":[]}],"summary":"Update access-granted duration for a user (creator only).","tags":["PackageAccess"]},"delete":{"operationId":"PackageAccessController_revoke","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Grant revoked."},"403":{"description":"Only the package creator can perform this action."},"404":{"description":"Grant not found."}},"security":[{"bearer":[]}],"summary":"Revoke access-granted role for a user (creator only).","tags":["PackageAccess"]},"get":{"operationId":"PackageAccessController_getUserRoles","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PackageAccessRolesResponseDto"}}}}}},"403":{"description":"Only the package creator can perform this action."}},"security":[{"bearer":[]}],"summary":"Get all access roles for a specific user for a package.","tags":["PackageAccess"]}},"/api/v1/package-access/{packageId}":{"get":{"operationId":"PackageAccessController_list","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}},{"name":"role","required":false,"in":"query","description":"Filter by role(s). Accepts a single value or an array.","schema":{"type":"array","items":{"type":"string","enum":["subscribed","purchased","granted"]}}},{"name":"isActive","required":false,"in":"query","description":"Filter by active state.","schema":{"type":"boolean"}},{"name":"search","required":false,"in":"query","description":"Search by username. Trimmed; very long inputs are truncated to reduce DB load.","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Page size","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PackageAccessResponseDto"}}}}}}},"403":{"description":"Only the package creator can perform this action."}},"security":[{"bearer":[]}],"summary":"Get all users with any role for a package (paginated, filterable).","tags":["PackageAccess"]}},"/api/v1/domains/register/{packageId}":{"post":{"operationId":"DomainsController_registerPackageDomain","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":"Domain registered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"403":{"description":"Not the package creator."},"404":{"description":"Package not found."},"409":{"description":"Domain already exists or package already has one."}},"security":[{"bearer":[]}],"summary":"Register a domain for a package (creator only).","tags":["domains"]}},"/api/v1/domains/register/subdomain/{serverId}":{"post":{"operationId":"DomainsController_registerServerSubdomain","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterSubdomainRequestDto"}}}},"responses":{"201":{"description":"Subdomain registered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainSubdomain"}}}},"403":{"description":"Not the server owner."},"404":{"description":"Package not found, server not found, or main domain not registered."},"409":{"description":"Subdomain label already exists."}},"security":[{"bearer":[]}],"summary":"Register a subdomain under a package main domain for a specific server.","tags":["domains"]}},"/api/v1/orders/create":{"post":{"operationId":"OrdersController_createWorldItemOrder","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorldItemOrderDto"}}}},"responses":{"200":{"description":"Order created successfully."},"400":{"description":"Failed to create order. Either worldItemId or worldItemSlug must be provided."},"401":{"description":"Unauthorized."},"403":{"description":"Only server creator can create orders for the server."},"404":{"description":"World item, server, or user not found."}},"security":[{"bearer":[]}],"summary":"Create an order for a world item for a user via server. The world item can be specified by either worldItemId or worldItemSlug. If both are provided, worldItemId takes precedence.","tags":["Orders"]}},"/api/v1/orders/server-plan":{"post":{"operationId":"OrdersController_createServerPlanOrder","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateServerPlanOrderDto"}}}},"responses":{"200":{"description":"Order created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponseDto"}}}},"400":{"description":"Invalid request or plan unavailable."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Create an order for a server plan subscription.","tags":["Orders"]}},"/api/v1/orders/escrow/{orderId}":{"patch":{"operationId":"OrdersController_escrowOrder","parameters":[{"name":"orderId","required":true,"in":"path","schema":{"type":"string"}},{"name":"x-lix-tag","required":true,"in":"header","schema":{"type":"string"}},{"name":"X-Lix-Tag","in":"header","description":"Signed message (MAC hash) for order verification. Message format: {orderId}#{userId}","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/OrderWithWalletResponseDto"}}}}}},"400":{"description":"Failed to escrow funds."},"401":{"description":"Unauthorized."},"404":{"description":"Order not found."}},"security":[{"bearer":[]}],"summary":"Escrow funds for an existing order (requires MAC verification via X-Lix-Tag header).","tags":["Orders"]}},"/api/v1/orders/decline/{orderId}":{"patch":{"operationId":"OrdersController_declineOrder","parameters":[{"name":"orderId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/OrderResponseDto"}}}}}},"400":{"description":"Order must be in Pending status to decline."},"401":{"description":"Unauthorized."},"404":{"description":"Order not found."}},"security":[{"bearer":[]}],"summary":"Decline (cancel) a pending order from the client side.","tags":["Orders"]}},"/api/v1/orders/release/{orderId}":{"patch":{"operationId":"OrdersController_releaseEscrow","parameters":[{"name":"orderId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/OrderResponseDto"}}}}}},"400":{"description":"Failed to release escrow or order not in Escrowed status."},"401":{"description":"Unauthorized."},"403":{"description":"Only server owner can release escrow for this order."},"404":{"description":"Order not found."}},"security":[{"bearer":[]}],"summary":"Release escrowed funds for an order (server owner only). Marks order as Paid.","tags":["Orders"]}},"/api/v1/orders/pending/latest":{"get":{"operationId":"OrdersController_getLatestPendingOrder","parameters":[{"name":"serverId","required":false,"in":"query","description":"Optional server ID to filter pending orders. If not provided, returns latest pending order from any server.","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/OrderWithWalletResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"No pending order found for the specified criteria."}},"security":[{"bearer":[]}],"summary":"Get the latest pending order for the current user. Optionally filter by server.","tags":["Orders"]}},"/api/v1/orders/me":{"get":{"operationId":"OrdersController_getMyOrders","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter orders by status","schema":{"example":"Pending","type":"string","enum":["Pending","Escrowed","Paid","Failed","Canceled","Refunded"]}},{"name":"serverId","required":false,"in":"query","description":"Filter orders by server ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderResponseDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get my orders (paginated). Optionally filter by status and/or server.","tags":["Orders"]}},"/api/v1/orders/me/{orderId}":{"get":{"operationId":"OrdersController_getMyOrderById","parameters":[{"name":"orderId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/OrderResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"Order not found."}},"security":[{"bearer":[]}],"summary":"Get a single my order by ID.","tags":["Orders"]}},"/api/v1/orders/servers/{serverId}":{"get":{"operationId":"OrdersController_getServerOrders","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter orders by one or more statuses","schema":{"example":["Escrowed","Failed"],"type":"array","items":{"type":"string","enum":["Pending","Escrowed","Paid","Failed","Canceled","Refunded"]}}},{"name":"userId","required":false,"in":"query","description":"Filter orders by user ID (get all orders for a specific user)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"updatedAfter","required":false,"in":"query","description":"Filter orders updated after this absolute date-time. Mutually exclusive with updatedWithinSeconds.","schema":{"format":"date-time","example":"2025-01-01T00:00:00.000Z","type":"string"}},{"name":"updatedWithinSeconds","required":false,"in":"query","description":"Filter orders updated within the last N seconds (relative to server time). Mutually exclusive with updatedAfter.","schema":{"minimum":1,"maximum":600,"example":120,"type":"number"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by","schema":{"default":"createdAt","type":"string","enum":["createdAt","updatedAt","totalAmount","status"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderResponseDto"}}}}}}},"401":{"description":"Unauthorized."},"403":{"description":"Only server creator can access server orders."},"404":{"description":"Server not found."}},"security":[{"bearer":[]}],"summary":"Get all orders for a server (server creator only).","tags":["Orders"]}},"/api/v1/ovh/instances":{"get":{"operationId":"OvhController_getAvailableInstances","parameters":[{"name":"vpsOnly","required":false,"in":"query","description":"Filter to return only VPS plans","schema":{"example":true,"type":"boolean"}},{"name":"baremetalOnly","required":false,"in":"query","description":"Filter to return only Baremetal plans","schema":{"example":true,"type":"boolean"}},{"name":"region","required":false,"in":"query","description":"Filter by region code (DE1, UK1, BHS5)","schema":{"example":"DE1","type":"string","enum":["DE1","UK1","BHS5"]}}],"responses":{"200":{"description":"Returns available VPS and Baremetal plans by region","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableInstancesResponseDto"}}}}},"summary":"Get available OVH hosting instances","tags":["OVH"]}},"/api/v1/kv-storage/plans":{"get":{"description":"Returns all active KV storage plans available for purchase.","operationId":"KvStoragePlansController_listPlans","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/KvStoragePlanResponseDto"}}}}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"List KV storage plans","tags":["KV Storage"]}},"/api/v1/kv-storage/subscribe":{"post":{"description":"Purchase a KV storage plan for a server using LIX. The server owner must be the authenticated user.","operationId":"KvStorageSubscriptionController_subscribe","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKvSubscriptionDto"}}}},"responses":{"201":{"description":"Subscription created successfully"},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Subscribe to a KV storage plan","tags":["KV Storage"]}},"/api/v1/kv-storage/servers/{serverId}/subscription":{"get":{"description":"Returns the current KV storage subscription and usage statistics for the specified server.","operationId":"KvStorageSubscriptionController_getSubscription","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/KvStorageSubscriptionResponseDto"}}}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get KV storage subscription for a server","tags":["KV Storage"]},"delete":{"description":"Cancel the KV storage subscription. For recurring plans, the subscription remains active until the end of the current billing period.","operationId":"KvStorageSubscriptionController_cancelSubscription","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/KvStorageSubscriptionResponseDto"}}}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Cancel KV storage subscription","tags":["KV Storage"]}},"/api/v1/kv-storage/servers/{serverId}/subscription/upgrade":{"patch":{"description":"Upgrade to a higher KV storage plan. A prorated charge will be applied for the remaining billing period.","operationId":"KvStorageSubscriptionController_upgradePlan","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeKvSubscriptionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/KvStorageSubscriptionResponseDto"}}}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Upgrade KV storage plan","tags":["KV Storage"]}},"/api/v1/kv-storage/servers/{serverId}/datastores":{"post":{"description":"Create a new named datastore within the server.","operationId":"KvStorageDataController_createDatastore","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDatastoreDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Create a datastore","tags":["KV Storage Data"]},"get":{"description":"List all datastores in the server.","operationId":"KvStorageDataController_listDatastores","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Cursor for pagination (optional). When provided, it takes precedence over page.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DatastoreResponseDto"}}}}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List datastores","tags":["KV Storage Data"]}},"/api/v1/kv-storage/servers/{serverId}/datastores/{name}":{"delete":{"description":"Delete a datastore and all its entries. This action is irreversible.","operationId":"KvStorageDataController_deleteDatastore","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Datastore deleted"},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Delete a datastore","tags":["KV Storage Data"]}},"/api/v1/kv-storage/servers/{serverId}/datastores/{name}/entries/{key}":{"get":{"description":"Retrieve a value by key from a datastore.","operationId":"KvStorageDataController_getEntry","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"}},{"name":"key","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntryResponseDto"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get an entry","tags":["KV Storage Data"]},"put":{"description":"Create or update a key-value entry in a datastore. Value can be any JSON-serializable data.","operationId":"KvStorageDataController_setEntry","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"}},{"name":"key","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetEntryDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetEntryResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Set an entry","tags":["KV Storage Data"]},"delete":{"description":"Delete a key-value entry from a datastore.","operationId":"KvStorageDataController_deleteEntry","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"}},{"name":"key","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Entry deleted"},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Delete an entry","tags":["KV Storage Data"]}},"/api/v1/kv-storage/servers/{serverId}/datastores/{name}/entries/batch-get":{"post":{"description":"Fetch multiple keys in a single request.","operationId":"KvStorageDataController_batchGetEntries","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchGetEntriesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchGetEntriesResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Batch get entries","tags":["KV Storage Data"]}},"/api/v1/kv-storage/servers/{serverId}/datastores/{name}/entries/batch-set":{"put":{"description":"Create or update multiple key-value entries in one request.","operationId":"KvStorageDataController_batchSetEntries","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchSetEntriesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchSetEntriesResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Batch set entries","tags":["KV Storage Data"]}},"/api/v1/kv-storage/servers/{serverId}/datastores/{name}/entries/batch-update":{"patch":{"description":"Apply shallow object patch updates to multiple keys in a single request.","operationId":"KvStorageDataController_batchUpdateEntries","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchUpdateEntriesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchUpdateEntriesResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Batch update entries","tags":["KV Storage Data"]}},"/api/v1/kv-storage/servers/{serverId}/datastores/{name}/entries/batch-delete":{"delete":{"description":"Delete multiple keys in a single request.","operationId":"KvStorageDataController_batchDeleteEntries","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchDeleteEntriesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchDeleteEntriesResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Batch delete entries","tags":["KV Storage Data"]}},"/api/v1/kv-storage/servers/{serverId}/datastores/{name}/logs/{stream}/append":{"post":{"description":"Append a log payload to a stream with idempotency key deduplication.","operationId":"KvStorageDataController_appendLog","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"}},{"name":"stream","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppendLogDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppendLogResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Append log entry idempotently","tags":["KV Storage Data"]}},"/api/v1/kv-storage/servers/{serverId}/datastores/{name}/entries":{"get":{"description":"List entries in a datastore with cursor-based pagination.","operationId":"KvStorageDataController_listEntries","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}},{"name":"name","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Cursor for pagination (optional). When provided, it takes precedence over page.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EntryResponseDto"}}}}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List entries","tags":["KV Storage Data"]}},"/api/v1/worlds/{worldId}/reviews":{"post":{"description":"Client tokens are not allowed on this route: This route is not supported at this time.","operationId":"WorldReviewsController_create[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorldReviewRequestDto"}}}},"responses":{"401":{"description":"Unauthorized."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"User or world not found."},"406":{"description":"Client token version is outdated."},"409":{"description":"User has already reviewed this world."}},"security":[{"bearer":[]}],"summary":"Create the caller’s review for a world.","tags":["World Reviews","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported at this time."}},"get":{"description":"Returns others' reviews (with messages), the thumbs-up percentage, and — when authenticated — the caller's own review in a separate field.","operationId":"WorldReviewsController_getWorldReviews[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Limit (items per page)","schema":{"default":10,"example":10,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldReviewsWithThumbsResponseDto"}}}},"401":{"description":"Unauthorized."},"404":{"description":"World not found."}},"security":[{"bearer":[]}],"summary":"Get paginated reviews for a world (with thumbs-up percentage).","tags":["World Reviews"]},"patch":{"operationId":"WorldReviewsController_update[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorldReviewRequestDto"}}}},"responses":{"401":{"description":"Unauthorized."},"404":{"description":"Review or world not found."}},"security":[{"bearer":[]}],"summary":"Update the caller’s review for a world.","tags":["World Reviews"]},"delete":{"operationId":"WorldReviewsController_delete[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Review deleted successfully."},"400":{"description":"Invalid worldId format."},"401":{"description":"Unauthorized."},"404":{"description":"Review not found."}},"security":[{"bearer":[]}],"summary":"Delete the caller’s review for a world.","tags":["World Reviews"]}},"/api/v1/instant-worlds/{worldId}/reviews":{"post":{"description":"Client tokens are not allowed on this route: This route is not supported at this time.","operationId":"WorldReviewsController_create[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorldReviewRequestDto"}}}},"responses":{"401":{"description":"Unauthorized."},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"User or world not found."},"406":{"description":"Client token version is outdated."},"409":{"description":"User has already reviewed this world."}},"security":[{"bearer":[]}],"summary":"Create the caller’s review for a world.","tags":["World Reviews","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported at this time."}},"get":{"description":"Returns others' reviews (with messages), the thumbs-up percentage, and — when authenticated — the caller's own review in a separate field.","operationId":"WorldReviewsController_getWorldReviews[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Limit (items per page)","schema":{"default":10,"example":10,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldReviewsWithThumbsResponseDto"}}}},"401":{"description":"Unauthorized."},"404":{"description":"World not found."}},"security":[{"bearer":[]}],"summary":"Get paginated reviews for a world (with thumbs-up percentage).","tags":["World Reviews"]},"patch":{"operationId":"WorldReviewsController_update[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorldReviewRequestDto"}}}},"responses":{"401":{"description":"Unauthorized."},"404":{"description":"Review or world not found."}},"security":[{"bearer":[]}],"summary":"Update the caller’s review for a world.","tags":["World Reviews"]},"delete":{"operationId":"WorldReviewsController_delete[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Review deleted successfully."},"400":{"description":"Invalid worldId format."},"401":{"description":"Unauthorized."},"404":{"description":"Review not found."}},"security":[{"bearer":[]}],"summary":"Delete the caller’s review for a world.","tags":["World Reviews"]}},"/api/v1/public/worlds/{worldId}/reviews":{"get":{"operationId":"PublicWorldReviewsController_getWorldReviews[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Limit (items per page)","schema":{"default":10,"example":10,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldReviewsWithThumbsResponseDto"}}}},"400":{"description":"Invalid world id. Must be a UUID."},"404":{"description":"World not found."}},"summary":"Get a world’s public ratings and reviews (unauthenticated).","tags":["World Reviews"]}},"/api/v1/public/instant-worlds/{worldId}/reviews":{"get":{"operationId":"PublicWorldReviewsController_getWorldReviews[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Limit (items per page)","schema":{"default":10,"example":10,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldReviewsWithThumbsResponseDto"}}}},"400":{"description":"Invalid world id. Must be a UUID."},"404":{"description":"World not found."}},"summary":"Get a world’s public ratings and reviews (unauthenticated).","tags":["World Reviews"]}},"/api/v1/tags":{"get":{"operationId":"TagsController_find","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TagResponseDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get all tags.","tags":["Tags"]}},"/api/v1/economy/ping":{"get":{"operationId":"EconomyController_ping","parameters":[],"responses":{"200":{"description":"Ping response","content":{"application/json":{"schema":{"example":{"message":"pong"}}}}}},"summary":"Ping the economy microservice via gRPC","tags":["Economy"]}},"/api/v1/subscriptions/plans":{"get":{"operationId":"SubscriptionsController_plans","parameters":[],"responses":{"200":{"description":""}},"tags":["Subscriptions"]}},"/api/v1/subscriptions":{"post":{"operationId":"SubscriptionsController_createSubscription","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriptionDto"}}}},"responses":{"201":{"description":""}},"tags":["Subscriptions"]}},"/api/v1/subscriptions/me":{"get":{"operationId":"SubscriptionsController_mySubscription","parameters":[],"responses":{"200":{"description":""}},"tags":["Subscriptions"]}},"/api/v1/subscriptions/cancel":{"post":{"operationId":"SubscriptionsController_cancel","parameters":[],"responses":{"201":{"description":""}},"tags":["Subscriptions"]}},"/api/v1/subscriptions/resume":{"post":{"operationId":"SubscriptionsController_resume","parameters":[],"responses":{"201":{"description":""}},"tags":["Subscriptions"]}},"/api/v1/homes/{homeId}/runtime-launch":{"post":{"description":"Client tokens are not allowed on this route: desktop home launches require an interactive login","operationId":"HomesController_createRuntimeLaunch","parameters":[{"name":"homeId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomeRuntimeLaunchAssignmentResponseDto"}}}}}},"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Mint a short-lived desktop runtime assignment for an accessible Home.","tags":["Homes","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: desktop home launches require an interactive login"}}},"/api/v1/homes":{"post":{"operationId":"HomesController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHomeRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Create an engine-agnostic universal home.","tags":["Homes"]}},"/api/v1/homes/me":{"get":{"operationId":"HomesController_listMine","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"visibility","required":false,"in":"query","schema":{"type":"string","enum":["draft","private","friends","unlisted","public"]}},{"name":"category","required":false,"in":"query","schema":{"type":"string","enum":["apartment","social_room","showroom","event_space","storefront","gallery","game_room","creator_hub","other"]}},{"name":"tag","required":false,"in":"query","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","schema":{"default":"recent","type":"string","enum":["recent","most_visited","most_expensive","most_items"]}},{"name":"maxContentMaturity","required":false,"in":"query","description":"Maximum content maturity to include. Unrated content is treated as general.","schema":{"type":"string","enum":["general","teen","mature","adult"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}}},"security":[{"bearer":[]}],"summary":"List the caller's homes.","tags":["Homes"]}},"/api/v1/homes/me/slots":{"get":{"description":"Homes you may LIVE IN at once. Ownership is unlimited — this is occupancy. Read this to draw a slot meter instead of discovering the cap by provoking a 409.","operationId":"HomesController_getSlots","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomeSlotsResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"The caller's home-slot roster.","tags":["Homes"]}},"/api/v1/homes/slug-available":{"get":{"description":"Home slugs are globally unique. With many homes per user a collision is routine, so creation should never be the first place a user learns their slug is taken.","operationId":"HomesController_slugAvailable","parameters":[{"name":"slug","required":true,"in":"query","description":"The slug to check. Lowercase letters, numbers and hyphens.","schema":{"example":"jacks-loft","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/SlugAvailabilityResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Is this home slug free — and if not, what is?","tags":["Homes"]}},"/api/v1/homes/move-in":{"post":{"description":"Occupies one home slot. Moving into a shell you have lived in before reopens that same residence with its slug, title, visitors and saved layout intact. 409 `home_slot_limit_reached` carries { used, limit, tier, nextTier, nextTierLimit } so the client can offer a swap or an upgrade instead of an error toast.","operationId":"HomesController_moveIn","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveIntoHomeRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Move into an owned home shell.","tags":["Homes"]}},"/api/v1/homes/residences/{id}/move-out":{"post":{"description":"Returns every placed item to your inventory and SAVES the layout, so moving back in can put it all back. The residence itself — slug, title, invites, visitors, votes — survives untouched.","operationId":"HomesController_moveOut","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/MoveOutResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Move out of a home, freeing its slot.","tags":["Homes"]}},"/api/v1/homes/residences/{id}/restore-layout":{"post":{"description":"Re-places every item you still own and that is currently free. Items that moved on are reported in `unavailable` with where they went — a restore never fails because you sold a lamp.","operationId":"HomesController_restoreLayout","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/RestoreLayoutResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Put the saved layout back.","tags":["Homes"]}},"/api/v1/homes/residences/{id}/release-items":{"post":{"description":"For a home locked by a downgrade: returns its items to your inventory while the home stays locked. Without this, furniture is stranded inside a home you cannot open until you pay again.","operationId":"HomesController_releaseItems","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/ReleaseItemsResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Recover items from a home without unlocking it.","tags":["Homes"]}},"/api/v1/homes/me/reconcile-slots":{"post":{"description":"Locks over-limit homes after a downgrade and unlocks them again after an upgrade — never deletes, never unplaces. Runs automatically on every subscription change; exposed for a client to force after checkout rather than waiting on a webhook.","operationId":"HomesController_reconcileSlots","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomeSlotsResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Re-check occupancy against the current plan.","tags":["Homes"]}},"/api/v1/homes/me/default":{"get":{"operationId":"HomesController_getOrCreateDefault","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Get or create the caller's default home.","tags":["Homes"]}},"/api/v1/homes/public":{"get":{"operationId":"HomesController_listPublic","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"visibility","required":false,"in":"query","schema":{"type":"string","enum":["draft","private","friends","unlisted","public"]}},{"name":"category","required":false,"in":"query","schema":{"type":"string","enum":["apartment","social_room","showroom","event_space","storefront","gallery","game_room","creator_hub","other"]}},{"name":"tag","required":false,"in":"query","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","schema":{"default":"recent","type":"string","enum":["recent","most_visited","most_expensive","most_items"]}},{"name":"maxContentMaturity","required":false,"in":"query","description":"Maximum content maturity to include. Unrated content is treated as general.","schema":{"type":"string","enum":["general","teen","mature","adult"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}}},"summary":"List public homes.","tags":["Homes"]}},"/api/v1/homes/by-slug/{slug}":{"get":{"operationId":"HomesController_getPublicBySlug","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}},"summary":"Get a public or unlisted home by slug.","tags":["Homes"]}},"/api/v1/homes/invited/me":{"get":{"operationId":"HomesController_listInvited","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"visibility","required":false,"in":"query","schema":{"type":"string","enum":["draft","private","friends","unlisted","public"]}},{"name":"category","required":false,"in":"query","schema":{"type":"string","enum":["apartment","social_room","showroom","event_space","storefront","gallery","game_room","creator_hub","other"]}},{"name":"tag","required":false,"in":"query","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","schema":{"default":"recent","type":"string","enum":["recent","most_visited","most_expensive","most_items"]}},{"name":"maxContentMaturity","required":false,"in":"query","description":"Maximum content maturity to include. Unrated content is treated as general.","schema":{"type":"string","enum":["general","teen","mature","adult"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}}},"security":[{"bearer":[]}],"summary":"List homes shared with the caller by invite.","tags":["Homes"]}},"/api/v1/homes/accessible/{id}":{"get":{"operationId":"HomesController_getAccessible","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Get a home the caller can enter by id.","tags":["Homes"]}},"/api/v1/homes/accessible/by-slug/{slug}":{"get":{"operationId":"HomesController_getAccessibleBySlug","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Get a home the caller can enter by slug.","tags":["Homes"]}},"/api/v1/homes/accessible/by-owner/{ownerId}":{"get":{"operationId":"HomesController_listAccessibleByOwner","parameters":[{"name":"ownerId","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"visibility","required":false,"in":"query","schema":{"type":"string","enum":["draft","private","friends","unlisted","public"]}},{"name":"category","required":false,"in":"query","schema":{"type":"string","enum":["apartment","social_room","showroom","event_space","storefront","gallery","game_room","creator_hub","other"]}},{"name":"tag","required":false,"in":"query","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","schema":{"default":"recent","type":"string","enum":["recent","most_visited","most_expensive","most_items"]}},{"name":"maxContentMaturity","required":false,"in":"query","description":"Maximum content maturity to include. Unrated content is treated as general.","schema":{"type":"string","enum":["general","teen","mature","adult"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}}},"security":[{"bearer":[]}],"summary":"List homes from an owner that the caller can enter.","tags":["Homes"]}},"/api/v1/homes/{id}/invites":{"post":{"operationId":"HomesController_createInvite","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHomeInviteRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomeInviteResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Invite a user to enter one of the caller homes.","tags":["Homes"]},"get":{"operationId":"HomesController_listInvites","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/HomeInviteResponseDto"}}}}}}}},"security":[{"bearer":[]}],"summary":"List invites for one of the caller homes.","tags":["Homes"]}},"/api/v1/homes/{id}/invites/{inviteId}":{"delete":{"operationId":"HomesController_revokeInvite","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"inviteId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"bearer":[]}],"summary":"Revoke a home invite.","tags":["Homes"]}},"/api/v1/homes/{id}/vote":{"put":{"operationId":"HomesController_castVote","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CastHomeVoteRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Cast (or change) the caller vote on a home (like / dislike).","tags":["Homes"]},"delete":{"operationId":"HomesController_removeVote","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Remove the caller vote from a home.","tags":["Homes"]}},"/api/v1/homes/{id}/vote/me":{"get":{"operationId":"HomesController_getMyVote","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get the caller current vote on a home.","tags":["Homes"]}},"/api/v1/homes/{id}":{"get":{"operationId":"HomesController_getMine","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Get one of the caller homes by id.","tags":["Homes"]},"delete":{"description":"Refuses while you live there (409 `home_is_active`) — move out first, which is the step that returns your furniture. Refuses while items are still inside (409 `home_not_empty`) unless `releaseItems=true`, which saves the layout and hands everything back before deleting. The shell instance is always returned to your inventory, never orphaned.","operationId":"HomesController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"releaseItems","required":false,"in":"query","description":"Explicitly consent to returning everything still inside this home to your inventory before it is deleted. Without it a non-empty home is refused with 409 `home_not_empty` and its item count, so nobody deletes a furnished house by accident.","schema":{"default":false,"type":"boolean"}}],"responses":{"204":{"description":""}},"security":[{"bearer":[]}],"summary":"Delete one of the caller homes.","tags":["Homes"]},"patch":{"operationId":"HomesController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHomeRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomeResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Update one of the caller homes.","tags":["Homes"]}},"/api/v1/homes/{id}/placements":{"post":{"operationId":"HomesController_placeItem","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceHomeItemRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomePlacementResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Place an owned universal item into a home.","tags":["Homes"]}},"/api/v1/homes/{id}/placements/{placementId}":{"patch":{"operationId":"HomesController_updatePlacement","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"placementId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHomePlacementRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/HomePlacementResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Update a home item placement transform or state.","tags":["Homes"]},"delete":{"operationId":"HomesController_removePlacement","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"placementId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"bearer":[]}],"summary":"Remove an item placement from a home.","tags":["Homes"]}},"/api/v1/homes/{homeId}/session":{"post":{"description":"Client tokens are not allowed on this route: Home sessions require an interactive login","operationId":"HomeMultiplayerController_createSession","parameters":[{"name":"homeId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHomeSessionRequestDto"}}}},"responses":{"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Mint a short-lived session for a multiplayer Home visit.","tags":["Homes","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: Home sessions require an interactive login"}}},"/api/v1/homes/{homeId}/join":{"post":{"operationId":"HomeMultiplayerController_join","parameters":[{"name":"homeId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"tags":["Homes"]}},"/api/v1/homes/{homeId}/voice-token":{"post":{"operationId":"HomeMultiplayerController_voiceToken","parameters":[{"name":"homeId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstantWorldVoiceTokenRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"tags":["Homes"]}},"/api/v1/homes/{homeId}/live-invites":{"post":{"description":"Client tokens are not allowed on this route: Home live invites require an interactive login","operationId":"HomeMultiplayerController_createLiveInvite","parameters":[{"name":"homeId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHomeLiveInviteRequestDto"}}}},"responses":{"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Mint a one-use pass into one exact live Home instance.","tags":["Homes","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: Home live invites require an interactive login"}}},"/api/v1/homes/{homeId}/instances":{"get":{"operationId":"HomeMultiplayerController_listInstances","parameters":[{"name":"homeId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List live multiplayer instances for an accessible Home.","tags":["Homes"]}},"/api/v1/home-live-invites/{inviteId}":{"get":{"operationId":"HomeLiveInvitesController_resolve","parameters":[{"name":"inviteId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Resolve a recipient-bound Home invite deep link.","tags":["Homes"]}},"/api/v1/home-live-invites/{inviteId}/homes/{homeId}":{"get":{"operationId":"HomeLiveInvitesController_readHome","parameters":[{"name":"inviteId","required":true,"in":"path","schema":{"type":"string"}},{"name":"homeId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Read the invited Home without granting permanent Home access.","tags":["Homes"]}},"/api/v1/worlds":{"post":{"operationId":"InstantWorldsController_create[0]","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInstantWorldRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InstantWorldResponseDto"}}}}}},"400":{"description":"The request body is invalid."},"409":{"description":"Slug already taken."}},"security":[{"bearer":[]}],"summary":"Create a new draft Instant World.","tags":["Instant Worlds"]},"get":{"operationId":"InstantWorldsController_listPublished[0]","parameters":[{"name":"limit","required":false,"in":"query","description":"Max worlds to return (1-50).","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque keyset cursor from a previous page.","schema":{"type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"Filter to published worlds created by this user id. Backs a profile's Creations tab without scanning or client-filtering the discovery catalogue.","schema":{"type":"string"}},{"name":"maxContentMaturity","required":false,"in":"query","description":"Highest content maturity tier to include in discovery results.","schema":{"type":"string","enum":["general","teen","mature","adult"]}},{"name":"tag","required":false,"in":"query","description":"Filter to published worlds carrying this tag (case-insensitive). Supports direct tag deep-links such as /worlds?tag=Racing.","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","description":"Case- and accent-insensitive substring search over title, slug, description, and tags, resolved SERVER-side over the whole published catalogue. Without it the frontend could only filter the one page it had already fetched, so any world older than the newest page was unfindable (HYPR-5024).","schema":{"maxLength":100,"type":"string"}},{"name":"featured","required":false,"in":"query","description":"Filter to the curated featured set (worlds with isFeatured = true). Lets the Featured row/tab resolve SERVER-side over the whole published catalogue instead of slicing one client-side page, so a featured world never drops out of Discover once 50 newer worlds are published.","schema":{"type":"boolean"}},{"name":"official","required":false,"in":"query","description":"Filter to first-party worlds (isOfficial = true), for the Official Worlds row/tab. Read-only discovery filter — it does not change the flag, which also gates world coin authority.","schema":{"type":"boolean"}},{"name":"sort","required":false,"in":"query","description":"Discovery ordering. `recent` (default) is the keyset-paginated newest first. `popular` ranks by a trailing-window popularity score (unique actors weighted above total entries) and returns a single ranked page — cursors do not apply to it.","schema":{"default":"recent","type":"string","enum":["recent","popular"]}},{"name":"engine","required":false,"in":"query","description":"Filter by world engine. Omitted (the default) applies NO engine filter: it returns every published world that has an active (playable) build, web or Unreal alike. Pass `web` for browser-playable worlds with a build, `unreal` for the whole Unreal catalogue including build-less legacy mirrors the launcher can still install, or `all` for `unreal` plus web-with-a-build in one keyset-paginated stream — `all` is BROADER than the default, not equal to it. Every value relaxes the ENGINE predicate ONLY — published-status, maturity and the active-build requirement are unchanged, so none can surface unlisted or draft work.","schema":{"type":"string","enum":["web","unreal","all"]}}],"responses":{"200":{"description":""}},"summary":"List published Instant Worlds (keyset-paginated).","tags":["Instant Worlds"]}},"/api/v1/instant-worlds":{"post":{"operationId":"InstantWorldsController_create[1]","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInstantWorldRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InstantWorldResponseDto"}}}}}},"400":{"description":"The request body is invalid."},"409":{"description":"Slug already taken."}},"security":[{"bearer":[]}],"summary":"Create a new draft Instant World.","tags":["Instant Worlds"]},"get":{"operationId":"InstantWorldsController_listPublished[1]","parameters":[{"name":"limit","required":false,"in":"query","description":"Max worlds to return (1-50).","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque keyset cursor from a previous page.","schema":{"type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"Filter to published worlds created by this user id. Backs a profile's Creations tab without scanning or client-filtering the discovery catalogue.","schema":{"type":"string"}},{"name":"maxContentMaturity","required":false,"in":"query","description":"Highest content maturity tier to include in discovery results.","schema":{"type":"string","enum":["general","teen","mature","adult"]}},{"name":"tag","required":false,"in":"query","description":"Filter to published worlds carrying this tag (case-insensitive). Supports direct tag deep-links such as /worlds?tag=Racing.","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","description":"Case- and accent-insensitive substring search over title, slug, description, and tags, resolved SERVER-side over the whole published catalogue. Without it the frontend could only filter the one page it had already fetched, so any world older than the newest page was unfindable (HYPR-5024).","schema":{"maxLength":100,"type":"string"}},{"name":"featured","required":false,"in":"query","description":"Filter to the curated featured set (worlds with isFeatured = true). Lets the Featured row/tab resolve SERVER-side over the whole published catalogue instead of slicing one client-side page, so a featured world never drops out of Discover once 50 newer worlds are published.","schema":{"type":"boolean"}},{"name":"official","required":false,"in":"query","description":"Filter to first-party worlds (isOfficial = true), for the Official Worlds row/tab. Read-only discovery filter — it does not change the flag, which also gates world coin authority.","schema":{"type":"boolean"}},{"name":"sort","required":false,"in":"query","description":"Discovery ordering. `recent` (default) is the keyset-paginated newest first. `popular` ranks by a trailing-window popularity score (unique actors weighted above total entries) and returns a single ranked page — cursors do not apply to it.","schema":{"default":"recent","type":"string","enum":["recent","popular"]}},{"name":"engine","required":false,"in":"query","description":"Filter by world engine. Omitted (the default) applies NO engine filter: it returns every published world that has an active (playable) build, web or Unreal alike. Pass `web` for browser-playable worlds with a build, `unreal` for the whole Unreal catalogue including build-less legacy mirrors the launcher can still install, or `all` for `unreal` plus web-with-a-build in one keyset-paginated stream — `all` is BROADER than the default, not equal to it. Every value relaxes the ENGINE predicate ONLY — published-status, maturity and the active-build requirement are unchanged, so none can surface unlisted or draft work.","schema":{"type":"string","enum":["web","unreal","all"]}}],"responses":{"200":{"description":""}},"summary":"List published Instant Worlds (keyset-paginated).","tags":["Instant Worlds"]}},"/api/v1/worlds/me":{"get":{"operationId":"InstantWorldsController_listMine[0]","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get all of the caller's Instant Worlds (any status).","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/me":{"get":{"operationId":"InstantWorldsController_listMine[1]","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get all of the caller's Instant Worlds (any status).","tags":["Instant Worlds"]}},"/api/v1/worlds/{slug}":{"get":{"operationId":"InstantWorldsController_getBySlug[0]","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InstantWorldResponseDto"}}}}}},"404":{"description":"World not found or not visible to you."}},"summary":"Get a published Instant World by slug OR id, with its play URL. The owner also sees their own draft/private world.","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/{slug}":{"get":{"operationId":"InstantWorldsController_getBySlug[1]","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InstantWorldResponseDto"}}}}}},"404":{"description":"World not found or not visible to you."}},"summary":"Get a published Instant World by slug OR id, with its play URL. The owner also sees their own draft/private world.","tags":["Instant Worlds"]}},"/api/v1/worlds/{worldId}/products":{"get":{"operationId":"InstantWorldsController_listProducts[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicInventoryUniversalItemResponseDto"}}}}}}},"404":{"description":"World not found."}},"summary":"List a world's registered in-world products as item cards (public catalog).","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/{worldId}/products":{"get":{"operationId":"InstantWorldsController_listProducts[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicInventoryUniversalItemResponseDto"}}}}}}},"404":{"description":"World not found."}},"summary":"List a world's registered in-world products as item cards (public catalog).","tags":["Instant Worlds"]}},"/api/v1/worlds/{worldId}/instances":{"get":{"operationId":"InstantWorldsController_listInstances[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorldInstanceResponseDto"}}}}}}},"404":{"description":"World not found."}},"summary":"List a world's live multiplayer room instances (ground truth from the room cluster, cached a few seconds; empty for single-player worlds or when live metrics are unavailable).","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/{worldId}/instances":{"get":{"operationId":"InstantWorldsController_listInstances[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorldInstanceResponseDto"}}}}}}},"404":{"description":"World not found."}},"summary":"List a world's live multiplayer room instances (ground truth from the room cluster, cached a few seconds; empty for single-player worlds or when live metrics are unavailable).","tags":["Instant Worlds"]}},"/api/v1/worlds/{id}":{"patch":{"operationId":"InstantWorldsController_update[0]","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInstantWorldRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InstantWorldResponseDto"}}}}}},"403":{"description":"You do not own this world, or it is suspended."},"404":{"description":"World not found."},"409":{"description":"Cannot publish without an active build."}},"security":[{"bearer":[]}],"summary":"Update an owned Instant World (title / status).","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/{id}":{"patch":{"operationId":"InstantWorldsController_update[1]","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInstantWorldRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InstantWorldResponseDto"}}}}}},"403":{"description":"You do not own this world, or it is suspended."},"404":{"description":"World not found."},"409":{"description":"Cannot publish without an active build."}},"security":[{"bearer":[]}],"summary":"Update an owned Instant World (title / status).","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/{worldId}/builds/scene-v2":{"post":{"description":"Strictly validates and seals the World profile without flattening authored terrain, streaming cells, LODs, lights, items, or surfaces. Native Scene packages have no implicit legacy fallback.","operationId":"InstantWorldBuildsController_publishNativeSceneV2","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Publish an authored HELIX Scene v2 package as this World.","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/{worldId}/builds":{"post":{"operationId":"InstantWorldBuildsController_createBuild","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInstantWorldBuildRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CreateInstantWorldBuildResponseDto"}}}}}},"400":{"description":"Invalid manifest or file list."},"403":{"description":"You do not own this world."},"409":{"description":"World is suspended."}},"security":[{"bearer":[]}],"summary":"Create a build: validate the manifest and presign uploads.","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/{worldId}/builds/{buildId}/finalize":{"post":{"operationId":"InstantWorldBuildsController_finalize","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"buildId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/FinalizeInstantWorldBuildResponseDto"}}}}}},"400":{"description":"Upload verification failed."},"403":{"description":"You do not own this world."},"404":{"description":"World or build not found."},"409":{"description":"Build is not in the uploading state."}},"security":[{"bearer":[]}],"summary":"Finalize a build: verify uploads byte-exact, activate it, and publish the world.","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/{worldId}/media/upload":{"post":{"operationId":"InstantWorldMediaController_presignUpload","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldMediaUploadRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/WorldMediaUploadTicketDto"}}}}}},"400":{"description":"Invalid content type or size."},"403":{"description":"You do not own this world."},"404":{"description":"World not found."}},"security":[{"bearer":[]}],"summary":"Presign an upload for a custom world thumbnail (or preview media).","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/{worldId}/media/finalize":{"post":{"operationId":"InstantWorldMediaController_finalize","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldMediaFinalizeRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InstantWorldResponseDto"}}}}}},"400":{"description":"Upload not found or key invalid."},"403":{"description":"You do not own this world."},"404":{"description":"World not found."}},"security":[{"bearer":[]}],"summary":"Finalize a media upload: verify the object and set it on the world.","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/{worldId}/media/youtube":{"post":{"description":"Accepts youtube.com/watch?v=, youtu.be/, /embed/, /shorts/, /live/ or a bare 11-char id. The reference is normalised to a video id and stored; no bytes are hosted. Uploaded video files are not accepted — use this instead.","operationId":"InstantWorldMediaController_setYoutube","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldYoutubeRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InstantWorldResponseDto"}}}}}},"400":{"description":"Not a valid YouTube link."},"403":{"description":"You do not own this world."},"404":{"description":"World not found."}},"security":[{"bearer":[]}],"summary":"Set the world's preview video from a YouTube link.","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/{worldId}/media":{"delete":{"operationId":"InstantWorldMediaController_clear","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"kind","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InstantWorldResponseDto"}}}}}},"403":{"description":"You do not own this world."},"404":{"description":"World not found."}},"security":[{"bearer":[]}],"summary":"Clear a media slot: thumbnail (reverts to the generated SVG), preview image, or preview video.","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/{worldId}/session":{"post":{"description":"Client tokens are not allowed on this route: world sessions require an interactive login","operationId":"InstantWorldSessionController_createSession","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InstantWorldSessionResponseDto"}}}}}},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"World not found."},"406":{"description":"Client token version is outdated."},"409":{"description":"World has no published build (browser worlds only; an Unreal world is minted a data-only session)."}},"security":[{"bearer":[]}],"summary":"Mint a short-lived, world-scoped session token for the authenticated player.","tags":["Instant Worlds","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: world sessions require an interactive login"}}},"/api/v1/instant-worlds/{worldId}/join":{"post":{"operationId":"InstantWorldRoomJoinController_join","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InstantWorldRoomJoinResponseDto"}}}}}},"401":{"description":"Missing/invalid world session, or it lacks the multiplayer scope."},"403":{"description":"World is suspended or not multiplayer."},"404":{"description":"World not found."},"409":{"description":"World has no published build."}},"security":[{"bearer":[]}],"summary":"Reserve a multiplayer room seat and mint a room credential for the authenticated world session.","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/{worldId}/voice-token":{"post":{"operationId":"InstantWorldVoiceTokenController_mint","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstantWorldVoiceTokenRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InstantWorldVoiceTokenResponseDto"}}}}}},"401":{"description":"Missing/invalid world session, or it lacks the multiplayer scope."},"403":{"description":"World is suspended or has no voice permission."},"404":{"description":"World not found, or voice is not configured."},"409":{"description":"World has no published build."}},"security":[{"bearer":[]}],"summary":"Mint a LiveKit voice token for the joined room instance of this world session.","tags":["Instant Worlds"]}},"/api/v1/worlds/{worldId}/runtime-launch":{"post":{"description":"Client tokens are not allowed on this route: desktop runtime launches require an interactive login","operationId":"RuntimeLaunchController_create[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRuntimeLaunchRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/RuntimeLaunchAssignmentResponseDto"}}}}}},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"World, activity, or entitlement not found."},"406":{"description":"Client token version is outdated."},"409":{"description":"No compatible desktop build metadata is available."}},"security":[{"bearer":[]}],"summary":"Mint a short-lived, user/build/activity-bound desktop runtime assignment.","tags":["Worlds","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: desktop runtime launches require an interactive login"}}},"/api/v1/instant-worlds/{worldId}/runtime-launch":{"post":{"description":"Client tokens are not allowed on this route: desktop runtime launches require an interactive login","operationId":"RuntimeLaunchController_create[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRuntimeLaunchRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/RuntimeLaunchAssignmentResponseDto"}}}}}},"403":{"description":"Client tokens are not allowed on this route."},"404":{"description":"World, activity, or entitlement not found."},"406":{"description":"Client token version is outdated."},"409":{"description":"No compatible desktop build metadata is available."}},"security":[{"bearer":[]}],"summary":"Mint a short-lived, user/build/activity-bound desktop runtime assignment.","tags":["Worlds","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: desktop runtime launches require an interactive login"}}},"/api/v1/worlds/{worldId}/builds/shared-runtime":{"post":{"operationId":"SharedRuntimeBuildsController_create[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSharedRuntimeBuildRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CreateSharedRuntimeBuildResponseDto"}}}}}},"403":{"description":"The caller does not own this World."},"409":{"description":"Replay conflict or suspended World."}},"security":[{"bearer":[]}],"summary":"Register a Shared-Runtime Build intent and presign immutable content uploads.","tags":["Worlds"]},"get":{"operationId":"SharedRuntimeBuildsController_listOwnerBuilds[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/SharedRuntimeBuildHistoryDto"}}}}}},"403":{"description":"The caller does not own this World."}},"security":[{"bearer":[]}],"summary":"List every Shared-Runtime Build for the owning creator, including lifecycle diagnostics and the active release marker.","tags":["Worlds"]}},"/api/v1/instant-worlds/{worldId}/builds/shared-runtime":{"post":{"operationId":"SharedRuntimeBuildsController_create[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSharedRuntimeBuildRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CreateSharedRuntimeBuildResponseDto"}}}}}},"403":{"description":"The caller does not own this World."},"409":{"description":"Replay conflict or suspended World."}},"security":[{"bearer":[]}],"summary":"Register a Shared-Runtime Build intent and presign immutable content uploads.","tags":["Worlds"]},"get":{"operationId":"SharedRuntimeBuildsController_listOwnerBuilds[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/SharedRuntimeBuildHistoryDto"}}}}}},"403":{"description":"The caller does not own this World."}},"security":[{"bearer":[]}],"summary":"List every Shared-Runtime Build for the owning creator, including lifecycle diagnostics and the active release marker.","tags":["Worlds"]}},"/api/v1/worlds/{worldId}/builds/{buildId}/shared-runtime/finalize":{"post":{"operationId":"SharedRuntimeBuildsController_finalize[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"buildId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/SharedRuntimeBuildReceiptDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Verify every uploaded byte by size and SHA-256, then countersign the immutable Build.","tags":["Worlds"]}},"/api/v1/instant-worlds/{worldId}/builds/{buildId}/shared-runtime/finalize":{"post":{"operationId":"SharedRuntimeBuildsController_finalize[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"buildId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/SharedRuntimeBuildReceiptDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Verify every uploaded byte by size and SHA-256, then countersign the immutable Build.","tags":["Worlds"]}},"/api/v1/worlds/{worldId}/builds/{buildId}/promote":{"post":{"operationId":"SharedRuntimeBuildsController_promote[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"buildId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromoteSharedRuntimeBuildRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/SharedRuntimeBuildReceiptDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Promote a validated Shared-Runtime Build. The same operation rolls back by promoting an older validated Build.","tags":["Worlds"]}},"/api/v1/instant-worlds/{worldId}/builds/{buildId}/promote":{"post":{"operationId":"SharedRuntimeBuildsController_promote[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"buildId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromoteSharedRuntimeBuildRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/SharedRuntimeBuildReceiptDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Promote a validated Shared-Runtime Build. The same operation rolls back by promoting an older validated Build.","tags":["Worlds"]}},"/api/v1/worlds/{worldId}/builds/{buildId}/revoke":{"post":{"operationId":"SharedRuntimeBuildsController_revoke[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"buildId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Revoke a Build signature at the authoritative delivery boundary and unpublish it if active.","tags":["Worlds"]}},"/api/v1/instant-worlds/{worldId}/builds/{buildId}/revoke":{"post":{"operationId":"SharedRuntimeBuildsController_revoke[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"buildId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Revoke a Build signature at the authoritative delivery boundary and unpublish it if active.","tags":["Worlds"]}},"/api/v1/worlds/{worldId}/builds/{buildId}/delivery/client":{"get":{"operationId":"SharedRuntimeBuildsController_clientDelivery[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"buildId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/SharedRuntimeBuildDeliveryDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Resolve the active Build manifest and short-lived client-role artifact downloads.","tags":["Worlds"]}},"/api/v1/instant-worlds/{worldId}/builds/{buildId}/delivery/client":{"get":{"operationId":"SharedRuntimeBuildsController_clientDelivery[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"buildId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/SharedRuntimeBuildDeliveryDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Resolve the active Build manifest and short-lived client-role artifact downloads.","tags":["Worlds"]}},"/api/v1/worlds/{worldId}/builds/{buildId}/delivery/node-template":{"get":{"operationId":"SharedRuntimeBuildsController_nodeTemplate[0]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"buildId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Return immutable logical server-role references for a managed hosting deployment. The Instance Controller replaces them with short-lived URLs at dispatch.","tags":["Worlds"]}},"/api/v1/instant-worlds/{worldId}/builds/{buildId}/delivery/node-template":{"get":{"operationId":"SharedRuntimeBuildsController_nodeTemplate[1]","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"buildId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Return immutable logical server-role references for a managed hosting deployment. The Instance Controller replaces them with short-lived URLs at dispatch.","tags":["Worlds"]}},"/api/v1/instant-worlds/scene-v2-assets/{integritySha256}/{assetPath}":{"get":{"operationId":"NativeSceneV2AssetsController_serve","parameters":[{"name":"integritySha256","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Serve a sealed local Scene v2 World object.","tags":["Instant Worlds"]}},"/api/v1/universal-items":{"post":{"description":"Creates the item immediately. Include an `assets` array to receive presigned upload URL(s) in the response (one `uploadUrl` for the web build, one per Unreal file). Upload the bytes to those URLs, then confirm each with POST /:id/assets/:assetId/finalize — an async worker then verifies, optimizes and thumbnails the mesh. An asset ships a web build (a single GLB), an Unreal build (a multi-file `files[]` set), or both.","operationId":"UniversalItemsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUniversalItemRequestDto"},"examples":{"webHomeItem":{"summary":"Home item with a web (GLB) build","value":{"slug":"neon-lounge-chair","title":"Neon Lounge Chair","description":"A glowing mid-century lounge chair.","kind":"home_item","category":"furniture","usage":"place","contentRating":"everyone","contentRatingAttestationAccepted":true,"assets":[{"rendition":"web","filename":"neon-lounge-chair.glb","mimeType":"model/gltf-binary","sizeBytes":204800}]}},"webAndUnreal":{"summary":"Item shipping both a web GLB and a multi-file Unreal build","value":{"slug":"neon-lounge-chair","title":"Neon Lounge Chair","kind":"home_item","category":"furniture","usage":"place","contentRating":"everyone","contentRatingAttestationAccepted":true,"assets":[{"rendition":"web","filename":"neon-lounge-chair.glb","sizeBytes":204800},{"rendition":"unreal","engineVersion":"5.7","targetPlatforms":["Win64"],"files":[{"key":"NeonChair-Windows.pak","size":120000},{"key":"NeonChair-Windows.utoc","size":8000},{"key":"NeonChair-Windows.ucas","size":2980000}]}]}},"minimal":{"summary":"Minimal item (metadata only — attach assets later)","value":{"slug":"neon-lounge-chair","title":"Neon Lounge Chair","kind":"home_item","category":"furniture","usage":"place","contentRating":"everyone","contentRatingAttestationAccepted":true}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UniversalItemResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Publish a universal item record.","tags":["Universal Items"]},"get":{"operationId":"UniversalItemsController_list","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Case-insensitive search over title and slug.","schema":{"example":"neon chair","type":"string"}},{"name":"tag","required":false,"in":"query","description":"Filter to items carrying this exact (normalised) tag.","schema":{"type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"Filter to items created by this user id. Backs a profile's Creations tab (all of a creator's published items, not just a page of the marketplace).","schema":{"type":"string"}},{"name":"kind","required":false,"in":"query","description":"Filter by item kind.","schema":{"example":"home_item","type":"string","enum":["wearable","home_item","home_shell","avatar","emote","prop","bundle","achievement","add_on","vehicle"]}},{"name":"category","required":false,"in":"query","description":"Filter by category.","schema":{"example":"furniture","type":"string","enum":["wearable","jackets","tops","bottoms","footwear","accessories","hair","makeup","body","furniture","decor","lighting","structure","utility","interactable","vehicle","collectible","misc"]}},{"name":"collectiblesOnly","required":false,"in":"query","description":"Return only items linked to a collectible template (collectible_id IS NOT NULL).","schema":{"type":"boolean"}},{"name":"slot","required":false,"in":"query","description":"Filter wearables by Character-Creator cosmetic slot tag (e.g. \"Cosmetic.Slot.Clothing.Top\").","schema":{"type":"string","enum":["Cosmetic.Slot.Clothing.Top","Cosmetic.Slot.Clothing.Bottoms","Cosmetic.Slot.Clothing.Set","Cosmetic.Slot.Clothing.Backpack","Cosmetic.Slot.Clothing.Socks","Cosmetic.Slot.Clothing.Shoes","Cosmetic.Slot.Clothing.Underwear.Top","Cosmetic.Slot.Clothing.Underwear.Bottom","Cosmetic.Slot.Clothing.Underwear.Leg","Cosmetic.Slot.Accessory.Head.Hat","Cosmetic.Slot.Accessory.Face.Mask","Cosmetic.Slot.Accessory.Face.Eyewear","Cosmetic.Slot.Accessory.Neck.Necklace","Cosmetic.Slot.Accessory.Ears.Earrings","Cosmetic.Slot.Accessory.Hands.Gloves","Cosmetic.Slot.Accessory.Hands.Nails","Cosmetic.Slot.Appearance.Hair.Main","Cosmetic.Slot.Appearance.Hair.Facial.Beard","Cosmetic.Slot.Appearance.Hair.Facial.Mustache","Cosmetic.Slot.Appearance.Eyes.Eyebrows","Cosmetic.Slot.Appearance.Eyes.Eyelashes","Cosmetic.Slot.Appearance.Eyes.Iris","Cosmetic.Slot.Appearance.Skin.BodyTattoo","Cosmetic.Slot.Appearance.Skin.FaceTattoo","Cosmetic.Slot.Appearance.Makeup.Lipstick","Cosmetic.Slot.Appearance.Makeup.Eyeliner","Cosmetic.Slot.Appearance.Makeup.Eyeshadow","Cosmetic.Slot.Appearance.Makeup.Blush","Cosmetic.Slot.Body.Head","Cosmetic.Slot.Body.Upper","Cosmetic.Slot.Body.Lower","Cosmetic.Slot.Body.Hands","Cosmetic.Slot.Body.Feet","Cosmetic.Slot.Custom"]}},{"name":"genders","required":false,"in":"query","description":"Filter wearables by Character-Creator gender. Repeat the param or send a comma-separated list; matching is OVERLAP (\"fits ANY of these\"), so ?genders=female returns unisex [\"male\",\"female\"] items as well as female-only ones.","schema":{"example":["male","female"],"type":"array","items":{"type":"string","enum":["male","female"]}}},{"name":"status","required":false,"in":"query","description":"Filter by status (admin listing only; the public list always returns published).","schema":{"example":"published","type":"string","enum":["draft","published","delisted","suspended","hidden","rejected","archived"]}},{"name":"maxContentMaturity","required":false,"in":"query","description":"Maximum content maturity to include. Unrated content is treated as general.","schema":{"type":"string","enum":["general","teen","mature","adult"]}},{"name":"slotType","required":false,"in":"query","description":"Filter to add-ons occupying this slot type, e.g. \"vehicle.exhaust@1\". Accepts a COMMA-SEPARATED SET (\"vehicle.wheel@1,vehicle.tyre@1\") for a whole part group — a group is exactly its openings, and without the set form the Marketplace's group chip could only reveal the level below it while leaving the grid unfiltered. Backed by idx_ui_slot_type.","schema":{"example":"vehicle.exhaust@1","type":"string"}},{"name":"hostKind","required":false,"in":"query","description":"THE ADD-ON CLASS FACET. Filter to items whose HOST is this class — `vehicle`, and whatever else publishes a slot board later (`character`, `weapon`). Backed by `idx_ui_host_kind`. It is the level ABOVE the part chips: an add-on stores its host class at publish (from the prefix of its slot type, prefix), and a base stores its own, so this one facet answers both \"show me vehicle add-ons\" and \"show me things that take add-ons\". Nothing new is authored for it and it cannot drift from what genuinely fits.","schema":{"example":"vehicle","type":"string"}},{"name":"subCategory","required":false,"in":"query","description":"VEHICLE SUB-TAXONOMY. Accepts either a SURFACE (`land` | `air` | `water`), which expands to the form factors under it, or a single form factor (`car`, `plane`, `boat`, ...). Resolved in SQL against `sub_category`. An unrecognised value is a 400, never a silently ignored filter that returns the whole catalogue.","schema":{"example":"water","type":"string"}},{"name":"fitsItem","required":false,"in":"query","description":"Filter to add-ons that FIT this base item — the compatibility predicate run against that base's published slot board and surface, not a text match on a title. An add-on whose requirements do not resolve on this base does not appear here at all.","schema":{"type":"string"}},{"name":"fitsOwned","required":false,"in":"query","description":"THE GARAGE FILTER. Return only add-ons that fit something the signed-in caller already owns. Requires authentication; ignored for anonymous viewers, who have no inventory to match against.","schema":{"type":"boolean"}},{"name":"cursor","required":false,"in":"query","description":"Opaque keyset cursor from a previous page (`pageInfo.nextCursor`). When supplied, results are returned via cursor pagination and the `page` param is ignored — this is the preferred, drift-free way to page a large catalog (infinite scroll).","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UniversalItemResponseDto"}}}}}}}},"summary":"List published universal items.","tags":["Universal Items"]}},"/api/v1/universal-items/scene-v2/upload":{"post":{"description":"Preserves authored streaming cells, LODs, mesh-ground terrain, lights and spawn data. Send the immutable Scene document in `scene`, ordered local resource bytes in repeated `resources` parts, and their canonical Scene bundle URIs in payload.sceneResourcePaths. Native packages do not acquire an implicit legacy world.json fallback.","operationId":"UniversalItemsController_uploadSceneV2","parameters":[],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Publish a native HELIX Scene v2 package as a Home shell.","tags":["Universal Items"]}},"/api/v1/universal-items/upload":{"post":{"description":"Server-buffer path: send the `.glb` in the `mesh` file part and item fields as a JSON string in the `payload` part. The server verifies the mesh inline (avatars must carry the converted helix-humanoid rig), stores it, and publishes the item. Prefer the presigned flow (POST /) for large browser uploads.","operationId":"UniversalItemsController_upload","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["mesh","payload"],"properties":{"mesh":{"type":"string","format":"binary","description":"The .glb mesh (binary glTF)."},"thumbnail":{"type":"string","format":"binary","description":"Optional thumbnail image; auto-generated when omitted."},"payload":{"type":"string","description":"JSON PublishUploadRequestDto (kind, title, category, ...).","example":"{\"kind\":\"home_item\",\"title\":\"Neon Lounge Chair\",\"category\":\"furniture\"}"}}}}}},"responses":{"200":{"description":"The published item plus the inline verification summary.","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/UniversalItemResponseDto"},"verification":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"warnings":{"type":"array","items":{"type":"string"},"example":[]},"summary":{"type":"object","example":{"triangleCount":4820,"boneNames":[],"maxTextureEdge":1024}}}}}}}}}},"security":[{"bearer":[]}],"summary":"Verify and publish an item from an uploaded mesh (avatar / home item).","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/home-shell/mesh":{"post":{"description":"Owner-only, home_shell-only. Re-runs the SAME shell-compiler pipeline `publish` uses (verify → compile → store bundle) against the new `.glb`, then swaps the existing `web` and `home-shell` rendition assets to point at the new geometry and republishes. Cosmetic/economic fields (title, price, collectible supply, slug) are untouched — use PATCH /:id for those. A verification failure or a compile failure leaves the LIVE item completely unchanged (checked before anything is written).","operationId":"UniversalItemsController_replaceHomeShellMesh","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["mesh"],"properties":{"mesh":{"type":"string","format":"binary","description":"The replacement .glb mesh (binary glTF)."}}}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Replace a published home_shell item's mesh IN PLACE (same item id, no new listing).","tags":["Universal Items"]}},"/api/v1/universal-items/avatar/import":{"post":{"description":"Accepts a raw generated/Mixamo/Meshy biped in the `mesh` part, retargets it to the engine rig (`helix-humanoid@1`) server-side (pure Node, no Blender), then verifies, stores, and publishes the converted avatar. Use this for raw rigs — the strict `/upload` endpoint rejects unconverted avatars. `payload` is a JSON PublishUploadRequestDto with kind:\"avatar\".","operationId":"UniversalItemsController_importAvatar","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["mesh","payload"],"properties":{"mesh":{"type":"string","format":"binary","description":"The raw rigged avatar .glb (Mixamo/Meshy biped or already helix-humanoid)."},"thumbnail":{"type":"string","format":"binary","description":"Optional thumbnail image; auto-generated when omitted."},"payload":{"type":"string","description":"JSON PublishUploadRequestDto (kind:\"avatar\", title, category, ...).","example":"{\"kind\":\"avatar\",\"title\":\"Middle Finger Warrior\"}"}}}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Import a RAW Mixamo/Meshy avatar, conform it to helix-humanoid, and publish.","tags":["Universal Items"]}},"/api/v1/universal-items/verify":{"post":{"description":"Parses + checks a `.glb` and returns the result WITHOUT persisting anything. A structurally invalid (non-GLB) file returns 400; a semantically invalid mesh (e.g. wrong skeleton) returns 200 with `ok:false` and `errors`.","operationId":"UniversalItemsController_verify","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["mesh","payload"],"properties":{"mesh":{"type":"string","format":"binary","description":"The .glb to check."},"payload":{"type":"string","description":"JSON with at least `kind` (and `title`).","example":"{\"kind\":\"avatar\",\"title\":\"Test Avatar\"}"}}}}}},"responses":{"200":{"description":"Verification result.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":false},"errors":{"type":"array","items":{"type":"string"},"example":["Avatar is not rigged to the helix-humanoid skeleton. Convert it first."]},"warnings":{"type":"array","items":{"type":"string"},"example":[]},"missingBones":{"type":"array","items":{"type":"string"},"example":[]},"rig":{"type":"string","nullable":true,"example":"mixamo"},"summary":{"type":"object","example":{"triangleCount":15200,"boneNames":[],"maxTextureEdge":2048}},"limitsApplied":{"type":"object","example":{"maxTriangles":60000}}}}}}}},"security":[{"bearer":[]}],"summary":"Dry-run verification of a mesh without publishing.","tags":["Universal Items"]}},"/api/v1/universal-items/publish-config":{"get":{"description":"The single source of truth for what publishing costs. Clients MUST render this rather than assuming. `publishFeeLix` is the one non-refundable fee charged when a definition first becomes public; 0 means waived. Drafts, edits, and distribution creation do not charge it. `minPriceLix` is the floor for positive Item Distribution prices. A creator may explicitly distribute at 0 LIX; a fee waiver does not choose the distribution price.","operationId":"UniversalItemsController_publishConfig","parameters":[],"responses":{"200":{"description":"Effective publication charges and price floors.","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","example":"LIX"},"kinds":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"publishFeeLix":{"type":"number"},"minPriceLix":{"type":"number"}}},"example":[{"kind":"wearable","publishFeeLix":75,"minPriceLix":250},{"kind":"avatar","publishFeeLix":180,"minPriceLix":500}]}}}}}}},"summary":"The Publish fee and minimum Item Distribution price per item kind.","tags":["Universal Items"]}},"/api/v1/universal-items/vehicle-taxonomy":{"get":{"description":"SERVED, not hard-coded client-side, for the same reason publish-config is: two copies of a vocabulary drift, and the copy that drifts is always the one a shopper is looking at. The first level is the SURFACE (land / air / water) — the same axis the vehicle solver already runs on (every entry in the engine socket table carries a `domain`, and `VehicleTuning` has land / water / air modules), so the aisle cannot disagree with how the vehicle behaves. The second is the form factor. Both are accepted by `?subCategory=` on the Marketplace and Inventory lists; a surface expands to its form factors server-side.","operationId":"UniversalItemsController_vehicleTaxonomy","parameters":[],"responses":{"200":{"description":"Surfaces, each with its form factors.","content":{"application/json":{"schema":{"type":"object","properties":{"surfaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"water"},"label":{"type":"string","example":"Water"},"formFactors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"boat"},"label":{"type":"string","example":"Boats"}}}}}}}}}}}}},"summary":"The vehicle sub-taxonomy: surfaces, and the form factors in each.","tags":["Universal Items"]}},"/api/v1/universal-items/publish-quote":{"post":{"operationId":"UniversalItemsController_publishQuote","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UniversalItemPublishQuoteRequestDto"}}}},"responses":{"200":{"description":"Authoritative publication and issuance quote.","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","example":"LIX"},"publishFeeLix":{"type":"number","example":75},"totalDueLix":{"type":"number","example":75}}}}}}},"security":[{"bearer":[]}],"summary":"Quote canonical edition, distribution, and the one Publish fee.","tags":["Universal Items"]}},"/api/v1/universal-items/mine/publish-fees":{"get":{"operationId":"UniversalItemsController_myPublishFees","parameters":[],"responses":{"200":{"description":"Publish-fee transaction references for the caller.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","format":"uuid"},"title":{"type":"string"},"kind":{"type":"string"},"transactionId":{"type":"string","format":"uuid"}}},"example":[{"itemId":"b3d1f2a4-5c6d-4e7f-8a9b-0c1d2e3f4a5b","title":"Neon Lounge Chair","kind":"home_item","transactionId":"e7c9a1b2-3d4e-4f5a-8b6c-7d8e9f0a1b2c"}]}}}}}}},"security":[{"bearer":[]}],"summary":"Map the caller's publish-fee transaction ids to their items (for wallet labels).","tags":["Universal Items"]}},"/api/v1/universal-items/assets/{groupId}/{filename}":{"put":{"operationId":"UniversalItemsController_uploadLocalAsset","parameters":[{"name":"groupId","required":true,"in":"path","schema":{"type":"string"}},{"name":"filename","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Accept a presigned-style upload for a locally-stored item asset (dev storage). In production, presigned uploadUrls point directly at R2 instead.","tags":["Universal Items"]}},"/api/v1/universal-items/assets/{groupId}/{assetPath}":{"get":{"operationId":"UniversalItemsController_serveAssetPath","parameters":[{"name":"groupId","required":true,"in":"path","schema":{"type":"string"}},{"name":"homeId","required":true,"in":"query","schema":{"type":"string"}},{"name":"placementId","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Serve a locally-stored item asset (dev storage). Also serves a compiled home shell's nested bundle files (`home-shell/world.json`, `home-shell/web/<meshId>.glb`).","tags":["Universal Items"]}},"/api/v1/universal-items/admin":{"get":{"operationId":"UniversalItemsController_listAdmin","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Case-insensitive search over title and slug.","schema":{"example":"neon chair","type":"string"}},{"name":"tag","required":false,"in":"query","description":"Filter to items carrying this exact (normalised) tag.","schema":{"type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"Filter to items created by this user id. Backs a profile's Creations tab (all of a creator's published items, not just a page of the marketplace).","schema":{"type":"string"}},{"name":"kind","required":false,"in":"query","description":"Filter by item kind.","schema":{"example":"home_item","type":"string","enum":["wearable","home_item","home_shell","avatar","emote","prop","bundle","achievement","add_on","vehicle"]}},{"name":"category","required":false,"in":"query","description":"Filter by category.","schema":{"example":"furniture","type":"string","enum":["wearable","jackets","tops","bottoms","footwear","accessories","hair","makeup","body","furniture","decor","lighting","structure","utility","interactable","vehicle","collectible","misc"]}},{"name":"collectiblesOnly","required":false,"in":"query","description":"Return only items linked to a collectible template (collectible_id IS NOT NULL).","schema":{"type":"boolean"}},{"name":"slot","required":false,"in":"query","description":"Filter wearables by Character-Creator cosmetic slot tag (e.g. \"Cosmetic.Slot.Clothing.Top\").","schema":{"type":"string","enum":["Cosmetic.Slot.Clothing.Top","Cosmetic.Slot.Clothing.Bottoms","Cosmetic.Slot.Clothing.Set","Cosmetic.Slot.Clothing.Backpack","Cosmetic.Slot.Clothing.Socks","Cosmetic.Slot.Clothing.Shoes","Cosmetic.Slot.Clothing.Underwear.Top","Cosmetic.Slot.Clothing.Underwear.Bottom","Cosmetic.Slot.Clothing.Underwear.Leg","Cosmetic.Slot.Accessory.Head.Hat","Cosmetic.Slot.Accessory.Face.Mask","Cosmetic.Slot.Accessory.Face.Eyewear","Cosmetic.Slot.Accessory.Neck.Necklace","Cosmetic.Slot.Accessory.Ears.Earrings","Cosmetic.Slot.Accessory.Hands.Gloves","Cosmetic.Slot.Accessory.Hands.Nails","Cosmetic.Slot.Appearance.Hair.Main","Cosmetic.Slot.Appearance.Hair.Facial.Beard","Cosmetic.Slot.Appearance.Hair.Facial.Mustache","Cosmetic.Slot.Appearance.Eyes.Eyebrows","Cosmetic.Slot.Appearance.Eyes.Eyelashes","Cosmetic.Slot.Appearance.Eyes.Iris","Cosmetic.Slot.Appearance.Skin.BodyTattoo","Cosmetic.Slot.Appearance.Skin.FaceTattoo","Cosmetic.Slot.Appearance.Makeup.Lipstick","Cosmetic.Slot.Appearance.Makeup.Eyeliner","Cosmetic.Slot.Appearance.Makeup.Eyeshadow","Cosmetic.Slot.Appearance.Makeup.Blush","Cosmetic.Slot.Body.Head","Cosmetic.Slot.Body.Upper","Cosmetic.Slot.Body.Lower","Cosmetic.Slot.Body.Hands","Cosmetic.Slot.Body.Feet","Cosmetic.Slot.Custom"]}},{"name":"genders","required":false,"in":"query","description":"Filter wearables by Character-Creator gender. Repeat the param or send a comma-separated list; matching is OVERLAP (\"fits ANY of these\"), so ?genders=female returns unisex [\"male\",\"female\"] items as well as female-only ones.","schema":{"example":["male","female"],"type":"array","items":{"type":"string","enum":["male","female"]}}},{"name":"status","required":false,"in":"query","description":"Filter by status (admin listing only; the public list always returns published).","schema":{"example":"published","type":"string","enum":["draft","published","delisted","suspended","hidden","rejected","archived"]}},{"name":"maxContentMaturity","required":false,"in":"query","description":"Maximum content maturity to include. Unrated content is treated as general.","schema":{"type":"string","enum":["general","teen","mature","adult"]}},{"name":"slotType","required":false,"in":"query","description":"Filter to add-ons occupying this slot type, e.g. \"vehicle.exhaust@1\". Accepts a COMMA-SEPARATED SET (\"vehicle.wheel@1,vehicle.tyre@1\") for a whole part group — a group is exactly its openings, and without the set form the Marketplace's group chip could only reveal the level below it while leaving the grid unfiltered. Backed by idx_ui_slot_type.","schema":{"example":"vehicle.exhaust@1","type":"string"}},{"name":"hostKind","required":false,"in":"query","description":"THE ADD-ON CLASS FACET. Filter to items whose HOST is this class — `vehicle`, and whatever else publishes a slot board later (`character`, `weapon`). Backed by `idx_ui_host_kind`. It is the level ABOVE the part chips: an add-on stores its host class at publish (from the prefix of its slot type, prefix), and a base stores its own, so this one facet answers both \"show me vehicle add-ons\" and \"show me things that take add-ons\". Nothing new is authored for it and it cannot drift from what genuinely fits.","schema":{"example":"vehicle","type":"string"}},{"name":"subCategory","required":false,"in":"query","description":"VEHICLE SUB-TAXONOMY. Accepts either a SURFACE (`land` | `air` | `water`), which expands to the form factors under it, or a single form factor (`car`, `plane`, `boat`, ...). Resolved in SQL against `sub_category`. An unrecognised value is a 400, never a silently ignored filter that returns the whole catalogue.","schema":{"example":"water","type":"string"}},{"name":"fitsItem","required":false,"in":"query","description":"Filter to add-ons that FIT this base item — the compatibility predicate run against that base's published slot board and surface, not a text match on a title. An add-on whose requirements do not resolve on this base does not appear here at all.","schema":{"type":"string"}},{"name":"fitsOwned","required":false,"in":"query","description":"THE GARAGE FILTER. Return only add-ons that fit something the signed-in caller already owns. Requires authentication; ignored for anonymous viewers, who have no inventory to match against.","schema":{"type":"boolean"}},{"name":"cursor","required":false,"in":"query","description":"Opaque keyset cursor from a previous page (`pageInfo.nextCursor`). When supplied, results are returned via cursor pagination and the `page` param is ignored — this is the preferred, drift-free way to page a large catalog (infinite scroll).","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UniversalItemResponseDto"}}}}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] List universal items by any status.","tags":["Universal Items"]}},"/api/v1/universal-items/inventory/me/summary":{"get":{"operationId":"UniversalItemsController_getInventorySummary","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InventorySummaryEntry"}}}}}},"security":[{"bearer":[]}],"summary":"Per-item instance count summary for the caller's inventory.","tags":["Universal Items"]}},"/api/v1/universal-items/inventory/me":{"get":{"operationId":"UniversalItemsController_listMine","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"itemId","required":false,"in":"query","schema":{"type":"string"}},{"name":"kind","required":false,"in":"query","schema":{"type":"string","enum":["wearable","home_item","home_shell","avatar","emote","prop","bundle","achievement","add_on","vehicle"]}},{"name":"category","required":false,"in":"query","schema":{"type":"string","enum":["wearable","jackets","tops","bottoms","footwear","accessories","hair","makeup","body","furniture","decor","lighting","structure","utility","interactable","vehicle","collectible","misc"]}},{"name":"subCategory","required":false,"in":"query","schema":{"example":"water","type":"string"}},{"name":"hostKind","required":false,"in":"query","schema":{"example":"vehicle","type":"string"}},{"name":"acquisitionWorldId","required":false,"in":"query","schema":{"type":"string"}},{"name":"locationType","required":false,"in":"query","schema":{"type":"string","enum":["inventory","home","world","listing","home_shell_in_use","equipped_on_item"]}},{"name":"equipped","required":false,"in":"query","schema":{"type":"boolean"}},{"name":"cursor","required":false,"in":"query","description":"Opaque keyset cursor from a previous page (`pageInfo.nextCursor`). When supplied, results are returned via cursor pagination (ordered by acquired-at) and the `page` param is ignored.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InventoryItemResponseDto"}}}}}}}},"security":[{"bearer":[]}],"summary":"List the caller's universal item inventory.","tags":["Universal Items"]}},"/api/v1/universal-items/inventory/users/{userId}":{"get":{"operationId":"UniversalItemsController_listUserInventory","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"itemId","required":false,"in":"query","schema":{"type":"string"}},{"name":"kind","required":false,"in":"query","schema":{"type":"string","enum":["wearable","home_item","home_shell","avatar","emote","prop","bundle","achievement","add_on","vehicle"]}},{"name":"category","required":false,"in":"query","schema":{"type":"string","enum":["wearable","jackets","tops","bottoms","footwear","accessories","hair","makeup","body","furniture","decor","lighting","structure","utility","interactable","vehicle","collectible","misc"]}},{"name":"subCategory","required":false,"in":"query","schema":{"example":"water","type":"string"}},{"name":"hostKind","required":false,"in":"query","schema":{"example":"vehicle","type":"string"}},{"name":"acquisitionWorldId","required":false,"in":"query","schema":{"type":"string"}},{"name":"locationType","required":false,"in":"query","schema":{"type":"string","enum":["inventory","home","world","listing","home_shell_in_use","equipped_on_item"]}},{"name":"equipped","required":false,"in":"query","schema":{"type":"boolean"}},{"name":"cursor","required":false,"in":"query","description":"Opaque keyset cursor from a previous page (`pageInfo.nextCursor`). When supplied, results are returned via cursor pagination (ordered by acquired-at) and the `page` param is ignored.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicInventoryItemResponseDto"}}}}}}}},"summary":"List a user's public universal item inventory.","tags":["Universal Items"]}},"/api/v1/universal-items/inventory/has/{itemId}":{"get":{"operationId":"UniversalItemsController_hasItem","parameters":[{"name":"itemId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"hasItem":{"type":"boolean","example":true}}}}}}},"security":[{"bearer":[]}],"summary":"Check whether the caller owns an available item.","tags":["Universal Items"]}},"/api/v1/universal-items/inventory/me/{inventoryItemId}/equip":{"patch":{"operationId":"UniversalItemsController_setEquipped","parameters":[{"name":"inventoryItemId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InventoryItemResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Equip or unequip one of the caller's inventory items.","tags":["Universal Items"]}},"/api/v1/universal-items/canvas/upload":{"post":{"description":"Send the image in the `image` file part. The server validates + transcodes (sharp), runs content moderation (rejects with 422, storing nothing), and stores the bytes on our CDN/R2. Returns { canvasAssetId, url }. Bind the id to a poster/frame instance via PATCH inventory/me/:id/canvas — never store a foreign URL.","operationId":"UniversalItemsController_uploadCanvasImage","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary","description":"The image file."}}}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Upload a canvas image: moderate + host on our CDN as an immutable asset id.","tags":["Universal Items"]}},"/api/v1/universal-items/inventory/me/{inventoryItemId}/canvas":{"patch":{"description":"Writes only state.canvasAssetId on the owned instance (spread-merged, never clobbering other state keys). Pass canvasAssetId:null to clear.","operationId":"UniversalItemsController_setCanvasAsset","parameters":[{"name":"inventoryItemId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InventoryItemResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Bind (or clear) a moderated canvas image on one of the caller's items.","tags":["Universal Items"]}},"/api/v1/universal-items/avatar/equipped/me":{"get":{"operationId":"UniversalItemsController_getMyEquippedAvatar","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquippedAvatarResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Resolve the caller's equipped universal avatar (equipped → auto-equip first owned → default).","tags":["Universal Items"]}},"/api/v1/universal-items/avatar/equipped/users/{userId}":{"get":{"operationId":"UniversalItemsController_getUserEquippedAvatar","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquippedAvatarResponseDto"}}}}},"summary":"Resolve a user's public equipped universal avatar.","tags":["Universal Items"]}},"/api/v1/universal-items/avatar/loadout/me":{"get":{"operationId":"UniversalItemsController_getMyAvatarLoadout","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get the caller's Universal Avatar Character Creator loadout and compatible inventory.","tags":["Universal Items"]},"patch":{"operationId":"UniversalItemsController_updateMyAvatarLoadout","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAvatarLoadoutRequestDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Autosave the caller's Universal Avatar Character Creator loadout.","tags":["Universal Items"]}},"/api/v1/universal-items/emotes/loadout/me":{"get":{"description":"Slots are r0..r7 (the quick-play wheel) plus sit and lie. An empty slot is null. Gated exactly like the public read, so what you edit is what other players see.","operationId":"UniversalItemsController_getMyEmoteLoadout","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmoteLoadoutResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get the caller's emote loadout (10 slots) and equippable emotes.","tags":["Universal Items"]},"patch":{"description":"Partial: only the slots named in `slots` change. Null empties a slot; an inventory instance id fills it, evicting whatever held it. An emote can only go in the slot family its own emoteCategory declares.","operationId":"UniversalItemsController_updateMyEmoteLoadout","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEmoteLoadoutRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmoteLoadoutResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Move emotes in the caller's slots.","tags":["Universal Items"]}},"/api/v1/universal-items/emotes/equipped/users/{userId}":{"get":{"description":"What the room and other players read. Slots that do not resolve to a clip are omitted; an empty sit/lie slot is filled with the platform default when one is configured.","operationId":"UniversalItemsController_getUserEquippedEmotes","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EquippedEmotesResponseDto"}}}}},"summary":"Resolve a user's playable emotes (slot → clip URL).","tags":["Universal Items"]}},"/api/v1/universal-items/avatar/loadout/me/placeholder-seed":{"post":{"operationId":"UniversalItemsController_seedMyAvatarPlaceholders","parameters":[],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Seed local placeholder avatar/wearable inventory for Character Creator QA.","tags":["Universal Items"]}},"/api/v1/universal-items/inventory/collectible-instances/{collectibleInstanceId}/admin/sync":{"post":{"operationId":"UniversalItemsController_syncCollectibleInstance","parameters":[{"name":"collectibleInstanceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncCollectibleInstanceInventoryRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InventoryItemResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Sync a scarce collectible instance into universal inventory.","tags":["Universal Items"]}},"/api/v1/universal-items/{id}":{"get":{"operationId":"UniversalItemsController_get","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UniversalItemResponseDto"}}}}}}},"summary":"Get a published universal item, or one of the authenticated creator’s own private items.","tags":["Universal Items"]},"patch":{"operationId":"UniversalItemsController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUniversalItemRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UniversalItemResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Update an owned universal item (creator only).","tags":["Universal Items"]},"delete":{"operationId":"UniversalItemsController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Delete an owned universal item (creator only). Rejected if any user owns it.","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/view":{"post":{"operationId":"UniversalItemsController_recordView","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"summary":"Record a view — a user opened this item’s preview/detail (web marketplace or the HELIX OS tablet). Deduped per viewer per day; returns the current view count.","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/stats":{"get":{"operationId":"UniversalItemsController_stats","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UniversalItemStatsResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Creator analytics for one item: real purchases, revenue, unique buyers, views and a 7-day trend from existing data. Creator-only.","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/assets":{"get":{"operationId":"UniversalItemsController_listAssets","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"List a published item's assets.","tags":["Universal Items"]},"post":{"description":"Returns the asset with presigned upload URL(s): a single `uploadUrl` for the web build, and one `uploadUrl` per entry in `files` for a multi-file Unreal build. PUT the bytes to those URLs, then call the finalize endpoint.","operationId":"UniversalItemsController_addAsset","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"x-engine-version","in":"header","description":"Engine version the Unreal files were cooked for. `5.7` is the current HELIX native runtime/cook target and is compatibility metadata, not a package-format version. OVERRIDES `engineVersion` in the body for an `unreal` asset (same behaviour as the package endpoints); IGNORED for every other rendition, so a UE tool may send it on every request.","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUniversalItemAssetRequestDto"},"examples":{"web":{"summary":"Web (GLB) build","value":{"rendition":"web","filename":"model.glb","mimeType":"model/gltf-binary","sizeBytes":204800}},"unreal":{"summary":"Cooked multi-file Unreal build","value":{"rendition":"unreal","engineVersion":"5.7","targetPlatforms":["Win64"],"files":[{"key":"ExampleJacket-Windows.pak","size":120000,"sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},{"key":"ExampleJacket-Windows.utoc","size":8000},{"key":"ExampleJacket-Windows.ucas","size":2980000}]}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UniversalItemAssetResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Add an asset (web and/or Unreal build) to an owned item.","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/assets/{assetId}":{"patch":{"description":"Send `filename`/`sizeBytes` to re-issue a presigned web `uploadUrl`, or `files` to (re-)declare the Unreal build — the response returns a fresh presigned `uploadUrl` per changed file. Any re-upload resets the asset to `awaiting_upload`.","operationId":"UniversalItemsController_updateAsset","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}},{"name":"x-engine-version","in":"header","description":"Engine version the Unreal files were cooked for. `5.7` is the current HELIX native runtime/cook target. Overrides `engineVersion` in the body for an `unreal` asset; ignored for every other rendition.","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUniversalItemAssetRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UniversalItemAssetResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Update one of an owned item's assets (e.g. attach an Unreal build).","tags":["Universal Items"]},"delete":{"operationId":"UniversalItemsController_removeAsset","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Remove one of an owned item's assets.","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/assets/{assetId}/finalize":{"post":{"description":"Any file that declared a `sha256` when it was created is re-read from storage and verified here. A mismatch (or missing bytes) fails with 422 `sha256_mismatch` and the asset stays `awaiting_upload` — re-upload and finalize again. Files with no declared digest are not checked. Idempotent: an asset that has already left `awaiting_upload` is returned unchanged, without re-scanning it.","operationId":"UniversalItemsController_finalizeAsset","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalizeUniversalItemAssetRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UniversalItemAssetResponseDto"}}}}}},"422":{"description":"A declared sha256 did not match the stored bytes, or the uploaded asset failed moderation."}},"security":[{"bearer":[]}],"summary":"Confirm a presigned upload completed and queue the asset for processing (verify → optimize → thumbnail).","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/purchase":{"post":{"description":"Universal Item definitions are unpriced. Use an exact Marketplace or World Item Distribution through the shell Claim/Buy flow.","operationId":"UniversalItemsController_purchase","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseUniversalItemRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UniversalItemPurchaseResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Deprecated direct-definition acquisition route.","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/mint":{"post":{"description":"Creator-only. Charges the platform mint fee and grants the creator one more instance. The fee goes to the platform and NO proceeds are paid back to the creator, so a self-mint never mints cashoutable value and never records a sale or moves the item’s trade statistics. The item must already be published (it must have its creator instance).","operationId":"UniversalItemsController_selfMint","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SelfMintUniversalItemRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UniversalItemSelfMintResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Mint an extra copy of your own item (self-mint).","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/publish":{"post":{"operationId":"UniversalItemsController_publishPersonalItem","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishPersonalItemRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UniversalItemResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Make one of your PERSONAL item definitions public. Publishing is unlimited for every tier; keeping items personal has no cap either.","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/delist":{"post":{"description":"Non-punitive, creator-triggered removal from acquisition and browse — the Etsy-style \"deactivate a listing\". Existing owners (including your own auto-granted instance) keep what they already have; nothing is revoked or quarantined. Only legal from a currently-published item; the admin-only suspend action (`/admin/moderate`) is the punitive counterpart and is unaffected by this route.","operationId":"UniversalItemsController_delist","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelistUniversalItemRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UniversalItemResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Unlist your own published item (creator only).","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/gift":{"post":{"operationId":"UniversalItemsController_gift","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftUniversalItemRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InventoryItemResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Gift an owned common universal item to a user.","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/admin/moderate":{"post":{"operationId":"UniversalItemsController_moderate","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerateUniversalItemRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UniversalItemResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Moderate a universal item.","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/admin/tags":{"post":{"description":"The only way to retag an item after publish (the creator PATCH excludes tags). Removes apply before adds; the result is normalised and capped like a publish. Curation tags: `avatar-starter` (the entry-flow roster) and `avatar-default` (the platform default avatar).","operationId":"UniversalItemsController_adminUpdateTags","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateItemTagsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UniversalItemResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Add or remove curation tags on a universal item.","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/admin/grant":{"post":{"operationId":"UniversalItemsController_grant","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantInventoryItemRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InventoryItemResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Grant a universal item to a user.","tags":["Universal Items"]}},"/api/v1/universal-items/{id}/slots":{"get":{"operationId":"AddOnsController_getSlots","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"The expanded slot board this item publishes, plus its surface digest.","tags":["add-ons"]},"put":{"description":"Widening is a MINOR change and applies to every owned instance at once. Removing a slot, changing a slot type, narrowing a grant or tightening thirdParty is refused unless `major: true` — and even then, existing owners stay pinned to the surface they bought.","operationId":"AddOnsController_putSlots","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishSlotBoardRequestDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Declare or refresh this item's slot board (creator or admin).","tags":["add-ons"]}},"/api/v1/universal-items/{id}/add-ons":{"get":{"description":"The compatibility predicate, not a text match. An add-on whose sockets or tunable paths do not resolve on this base does not appear here, and the total is counted AFTER the predicate runs.","operationId":"AddOnsController_listAddOnsForBase","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"slotType","required":false,"in":"query","schema":{"example":"vehicle.exhaust@1","type":"string"}},{"name":"owned","required":false,"in":"query","description":"true = only add-ons you already own (the in-game menu); false = only ones you do not (the catalogue-side \"shop this slot\"). Omit for both.","schema":{"type":"boolean"}},{"name":"offset","required":false,"in":"query","schema":{"default":0,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"default":50,"type":"number"}}],"responses":{"200":{"description":""}},"summary":"Add-ons that FIT this base item.","tags":["add-ons"]}},"/api/v1/universal-items/{id}/fits":{"get":{"operationId":"AddOnsController_listFits","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"offset","required":true,"in":"query","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Base items this ADD-ON fits — a computed count, never a claim.","tags":["add-ons"]}},"/api/v1/universal-items/validate-fit":{"post":{"operationId":"AddOnsController_validateFit","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateFitRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Creator dry-run: does this draft add-on publish, and what does it actually fit?","tags":["add-ons"]}},"/api/v1/universal-items/inventory/me/{inventoryItemId}/compose":{"post":{"operationId":"AddOnsController_compose","parameters":[{"name":"inventoryItemId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComposeRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Install / remove add-ons on one of your items and mint the digest.","tags":["add-ons"]}},"/api/v1/universal-items/inventory/me/{inventoryItemId}/board":{"get":{"description":"The base, its openings, what is installed in each, every add-on you own that fits, and every one you could buy that would. Factory-fitted parts are settled on read, so a base bought before its creator declared them still arrives fitted.","operationId":"AddOnsController_board","parameters":[{"name":"inventoryItemId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Everything the equip screen needs for one of your items.","tags":["add-ons"]}},"/api/v1/universal-items/inventory/me/{inventoryItemId}/builds":{"get":{"operationId":"AddOnsController_builds","parameters":[{"name":"inventoryItemId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Saved builds on one of your items.","tags":["add-ons"]}},"/api/v1/universal-items/inventory/{inventoryItemId}/xray":{"get":{"operationId":"AddOnsController_xray","parameters":[{"name":"inventoryItemId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Inspect another player's build and what it is worth.","tags":["add-ons"]}},"/api/v1/item-slot-types":{"get":{"operationId":"ItemSlotTypesController_list","parameters":[{"name":"hostKind","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"List the published slot types.","tags":["add-ons"]}},"/api/v1/item-slot-types/classes":{"get":{"description":"THE FIRST LEVEL OF THE ADD-ONS AISLE. The list is authored, so the Marketplace can offer Avatars and Weapons before anything is published into them — every other tab opens on a full row of subcategories and Add-ons should not be the one that opens on a single chip. `openings` is COMPUTED from the slot registry, so an aisle can never claim to be ready when nothing fits in it, and a client renders `openings: 0` as an honest empty state rather than hiding the class. A class carrying openings that nobody declared is appended rather than dropped.","operationId":"ItemSlotTypesController_listClasses","parameters":[],"responses":{"200":{"description":""}},"summary":"The add-on base classes, and how many openings each really has.","tags":["add-ons"]}},"/api/v1/compositions/{digest}":{"get":{"operationId":"CompositionsController_get","parameters":[{"name":"digest","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"The composed build for a digest. Immutable.","tags":["add-ons"]}},"/api/v1/creator-groups":{"get":{"operationId":"CreatorGroupsController_listMine","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Groups the caller belongs to.","tags":["creator-groups"]},"post":{"operationId":"CreatorGroupsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCreatorGroupRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Create a creator group.","tags":["creator-groups"]}},"/api/v1/creator-groups/invites/me":{"get":{"operationId":"CreatorGroupsController_myInvites","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Group invites waiting for the caller.","tags":["creator-groups"]}},"/api/v1/creator-groups/{groupId}":{"patch":{"description":"Safe by construction: a handle never reaches a published board or a published `fits` block — both hold the UUID, frozen at publish — so a rename can never re-point fitment or widen a slot lock.","operationId":"CreatorGroupsController_rename","parameters":[{"name":"groupId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCreatorGroupRequestDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Rename a group.","tags":["creator-groups"]}},"/api/v1/creator-groups/{groupId}/members":{"get":{"operationId":"CreatorGroupsController_members","parameters":[{"name":"groupId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List a group’s members.","tags":["creator-groups"]}},"/api/v1/creator-groups/{groupId}/invites":{"post":{"operationId":"CreatorGroupsController_invite","parameters":[{"name":"groupId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteCreatorGroupMemberRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Invite a creator to a group.","tags":["creator-groups"]}},"/api/v1/creator-groups/invites/{inviteId}/accept":{"post":{"operationId":"CreatorGroupsController_accept","parameters":[{"name":"inviteId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Accept a group invite.","tags":["creator-groups"]}},"/api/v1/creator-groups/{groupId}/members/{userId}":{"delete":{"operationId":"CreatorGroupsController_remove","parameters":[{"name":"groupId","required":true,"in":"path","schema":{"type":"string"}},{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Remove a member from a group.","tags":["creator-groups"]}},"/api/v1/creator-groups/{groupId}/transfer":{"post":{"operationId":"CreatorGroupsController_transfer","parameters":[{"name":"groupId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferCreatorGroupRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Transfer ownership of a group.","tags":["creator-groups"]}},"/api/v1/instant-packages/_ops/runtime-range-health":{"get":{"operationId":"InstantPackagesController_rangeHealth","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Alert check: every live world whose declared platform range no longer resolves.","tags":["Instant Packages"]}},"/api/v1/instant-packages/{slug}/versions":{"post":{"operationId":"InstantPackagesController_create","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInstantPackageVersionRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Create a package version: validate the envelope and presign uploads.","tags":["Instant Packages"]}},"/api/v1/instant-packages/{slug}/versions/{version}/finalize":{"post":{"operationId":"InstantPackagesController_finalize","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}},{"name":"version","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Finalize a version: verify uploads byte-exact and activate it.","tags":["Instant Packages"]}},"/api/v1/instant-packages/{slug}/versions/{version}/deactivate":{"post":{"operationId":"InstantPackagesController_deactivate","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}},{"name":"version","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeactivateInstantPackageVersionRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Kill switch: pull an active version out of runtime resolution (propagates in ~60s).","tags":["Instant Packages"]}},"/api/v1/instant-packages/{slug}/versions/{version}/reactivate":{"post":{"operationId":"InstantPackagesController_reactivate","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}},{"name":"version","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReactivateInstantPackageVersionRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Return a deactivated version to resolution, STAGED (rolloutPercent defaults to 0).","tags":["Instant Packages"]}},"/api/v1/instant-packages/{slug}/versions/{version}/rollout":{"post":{"operationId":"InstantPackagesController_rollout","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}},{"name":"version","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetInstantPackageVersionRolloutRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Set the staged rollout percentage for an active version.","tags":["Instant Packages"]}},"/api/v1/instant-packages/{slug}/versions/{version}/audits":{"get":{"operationId":"InstantPackagesController_audits","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}},{"name":"version","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Who deactivated or promoted this version, when, and why.","tags":["Instant Packages"]}},"/api/v1/instant-packages/{slug}/versions/{version}/product":{"post":{"operationId":"InstantPackagesController_product","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}},{"name":"version","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Create or update the official free Marketplace item linked to an active interactable bundle.","tags":["Instant Packages"]}},"/api/v1/instant-packages":{"get":{"operationId":"PublicInstantPackagesController_list","parameters":[{"name":"kind","required":false,"in":"query","schema":{"type":"string","enum":["system","ability","asset-pack","interactable"]}},{"name":"system","required":false,"in":"query","description":"Filter abilities by their host system id.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque keyset cursor.","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"List published packages (keyset-paginated).","tags":["Instant Packages"]}},"/api/v1/instant-packages/{slug}":{"get":{"operationId":"PublicInstantPackagesController_bySlug","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Get a package and its active versions.","tags":["Instant Packages"]}},"/api/v1/instant-packages/{slug}/versions/{version}":{"get":{"operationId":"PublicInstantPackagesController_version","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}},{"name":"version","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Get a version (manifest, payload, file lists, CDN URLs). :version may be \"latest\".","tags":["Instant Packages"]}},"/api/v1/instant-packages/{slug}/runtime/{range}/{modulePath}":{"get":{"operationId":"PublicInstantPackagesController_compatibleRuntimeModule","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}},{"name":"range","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Resolve a compatible platform system module to one immutable finalized catalog version. An optional `@world/<worldId>/` prefix on the module path is the staged-rollout cohort key.","tags":["Instant Packages"]}},"/api/v1/iwp/creator/worlds":{"get":{"operationId":"IwpController_listCreatorWorlds","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List the caller's published worlds with registered in-world products.","tags":["In-World Purchases"]}},"/api/v1/iwp/creator/worlds/{worldId}/products":{"get":{"operationId":"IwpController_listCreatorWorldProducts","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List registered in-world products for one of the caller's worlds.","tags":["In-World Purchases"]}},"/api/v1/iwp/products":{"post":{"operationId":"IwpController_registerProduct","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterWorldProductRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Register a purchasable product on a world.","tags":["In-World Purchases"]}},"/api/v1/iwp/products/{productId}":{"patch":{"operationId":"IwpController_updateProduct","parameters":[{"name":"productId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorldProductRequestDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Update a world product.","tags":["In-World Purchases"]},"get":{"operationId":"IwpController_getProduct","parameters":[{"name":"productId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get a world product.","tags":["In-World Purchases"]}},"/api/v1/iwp/products/{productId}/active":{"post":{"operationId":"IwpController_setProductActive","parameters":[{"name":"productId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetProductActiveRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Activate or deactivate a world product.","tags":["In-World Purchases"]}},"/api/v1/iwp/context":{"get":{"operationId":"IwpController_getContext","parameters":[{"name":"ref","required":true,"in":"query","schema":{"type":"string"}},{"name":"worldId","required":true,"in":"query","schema":{"type":"string"}},{"name":"quantity","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Product/listing + the caller’s live LIX balance + eligibility, in one call (for the confirm popup).","tags":["In-World Purchases"]}},"/api/v1/iwp/purchase":{"post":{"operationId":"IwpController_purchase","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IwpPurchaseRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Server-authoritative, idempotent purchase / claim.","tags":["In-World Purchases"]}},"/api/v1/iwp/purchase/{idempotencyKey}":{"get":{"operationId":"IwpController_getPurchase","parameters":[{"name":"idempotencyKey","required":true,"in":"path","schema":{"type":"string"}},{"name":"worldId","required":true,"in":"query","schema":{"type":"string"}},{"name":"ref","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Current status of a purchase (resume after a dropped connection).","tags":["In-World Purchases"]}},"/api/v1/iwp/creator/analytics/overview":{"get":{"operationId":"IwpAnalyticsController_getOverview","parameters":[{"name":"from","required":false,"in":"query","description":"Inclusive ISO timestamp lower bound.","schema":{"example":"2026-07-01T00:00:00.000Z","type":"string"}},{"name":"to","required":false,"in":"query","description":"Inclusive ISO timestamp upper bound.","schema":{"example":"2026-07-31T23:59:59.999Z","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorCommerceOverviewResponseDto"}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Account-wide in-world commerce overview across the caller's owned worlds.","tags":["In-World Purchases"]}},"/api/v1/iwp/creator/analytics/worlds/{worldId}":{"get":{"operationId":"IwpAnalyticsController_getWorldAnalytics","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","description":"Inclusive ISO timestamp lower bound.","schema":{"example":"2026-07-01T00:00:00.000Z","type":"string"}},{"name":"to","required":false,"in":"query","description":"Inclusive ISO timestamp upper bound.","schema":{"example":"2026-07-31T23:59:59.999Z","type":"string"}},{"name":"grain","required":false,"in":"query","schema":{"default":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorWorldAnalyticsResponseDto"}}}},"401":{"description":"Unauthorized."},"404":{"description":"World not found."}},"security":[{"bearer":[]}],"summary":"Per-world in-world commerce analytics with range and grain trend data.","tags":["In-World Purchases"]}},"/api/v1/iwp/creator/analytics/products/{productId}":{"get":{"operationId":"IwpAnalyticsController_getProductAnalytics","parameters":[{"name":"productId","required":true,"in":"path","schema":{"type":"string"}},{"name":"from","required":false,"in":"query","description":"Inclusive ISO timestamp lower bound.","schema":{"example":"2026-07-01T00:00:00.000Z","type":"string"}},{"name":"to","required":false,"in":"query","description":"Inclusive ISO timestamp upper bound.","schema":{"example":"2026-07-31T23:59:59.999Z","type":"string"}},{"name":"grain","required":false,"in":"query","schema":{"default":"day","type":"string","enum":["day","week","month"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorProductAnalyticsResponseDto"}}}},"401":{"description":"Unauthorized."},"404":{"description":"Product not found."}},"security":[{"bearer":[]}],"summary":"Per-product in-world commerce analytics for products on owned worlds.","tags":["In-World Purchases"]}},"/api/v1/iwp/creator/analytics/purchases":{"get":{"operationId":"IwpAnalyticsController_getPurchaseLedger","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"from","required":false,"in":"query","description":"Inclusive ISO timestamp lower bound.","schema":{"example":"2026-07-01T00:00:00.000Z","type":"string"}},{"name":"to","required":false,"in":"query","description":"Inclusive ISO timestamp upper bound.","schema":{"example":"2026-07-31T23:59:59.999Z","type":"string"}},{"name":"worldId","required":false,"in":"query","description":"Limit the ledger to one owned world.","schema":{"type":"string"}},{"name":"productId","required":false,"in":"query","description":"Limit the ledger to one product on an owned world.","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Limit the ledger to one purchase status.","schema":{"type":"string","enum":["Pending","Granted","Claimed","AlreadyOwned","InsufficientFunds","MaxPerUserReached","ProductInactive","ProductNotFound","NotInWorld","Unauthorized","RateLimited","Cancelled","Failed","Timeout","PriceChanged"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CreatorPurchaseLedgerEntryDto"}}}}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Paginated purchase ledger for the caller's owned worlds and products.","tags":["In-World Purchases"]}},"/api/v1/iwp/entitlements":{"get":{"operationId":"EntitlementsController_getOwn","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"The calling player's own entitlements in the calling world.","tags":["In-World Purchases"]}},"/api/v1/iwp/entitlements/{sub}":{"get":{"operationId":"EntitlementsController_getForPlayer","parameters":[{"name":"sub","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"A named player's entitlements — room lane only (seat hydrate).","tags":["In-World Purchases"]}},"/api/v1/iwp/entitlements/consume":{"post":{"operationId":"EntitlementsController_consume","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsumeEntitlementRequestDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Atomic, idempotent spend of a named balance (floor-at-zero rejection).","tags":["In-World Purchases"]}},"/api/v1/iwp/purchase-events/claim":{"post":{"operationId":"PurchaseEventsController_claim","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimPurchaseEventRequestDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"One-shot claim of a settled purchase's room event (room lane; first claimant wins).","tags":["In-World Purchases"]}},"/api/v1/coins/balance/me":{"get":{"operationId":"CoinsController_getBalance","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CoinBalanceResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"Get the caller's coin balance.","tags":["Coins"]}},"/api/v1/coins/transactions/me":{"get":{"operationId":"CoinsController_listMine","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"type","required":false,"in":"query","schema":{"type":"string","enum":["earn","spend","grant","refund","adjustment"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CoinTransactionResponseDto"}}}}}}}},"security":[{"bearer":[]}],"summary":"List the caller's coin transactions.","tags":["Coins"]}},"/api/v1/coins/world/earn":{"post":{"operationId":"CoinsController_earnFromWorld","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldCoinMutationRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CoinTransactionResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"[WORLD] Credit coins from an authorized world.","tags":["Coins"]}},"/api/v1/coins/world/spend":{"post":{"operationId":"CoinsController_spendFromWorld","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldCoinMutationRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CoinTransactionResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"[WORLD] Debit coins from an authorized world.","tags":["Coins"]}},"/api/v1/coins/admin/grant":{"post":{"operationId":"CoinsController_grant","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustCoinsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CoinTransactionResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Grant coins to a user.","tags":["Coins"]}},"/api/v1/coins/admin/spend":{"post":{"operationId":"CoinsController_spend","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustCoinsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CoinTransactionResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Debit coins from a user.","tags":["Coins"]}},"/api/v1/coins/debug/top-up/me":{"post":{"operationId":"CoinsController_debugTopUpMine","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DebugCoinMutationRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CoinTransactionResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"[DEBUG] Grant coins to the authenticated test account.","tags":["Coins"]}},"/api/v1/coins/debug/spend/me":{"post":{"operationId":"CoinsController_debugSpendMine","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DebugCoinMutationRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CoinTransactionResponseDto"}}}}}}},"security":[{"bearer":[]}],"summary":"[DEBUG] Debit coins from the authenticated test account.","tags":["Coins"]}},"/api/v1/coins/admin/worlds/{worldId}/coin-authority":{"patch":{"operationId":"CoinsController_updateWorldCoinAuthority","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorldCoinAuthorityRequestDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Configure world coin authority.","tags":["Coins"]}},"/api/v1/hosting/assignments/{assignmentId}":{"get":{"operationId":"JoinAssignmentController_get","parameters":[{"name":"assignmentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"tags":["Hosting"]}},"/api/v1/hosting/instances/{instanceId}/assignments/{assignmentId}/runtime-capability":{"post":{"operationId":"JoinAssignmentController_runtimeCapability","parameters":[{"name":"instanceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"assignmentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"tags":["Hosting"]}},"/api/v1/hosting/instances/{instanceId}/assignments/{assignmentId}/voice-token":{"post":{"operationId":"JoinAssignmentController_voiceToken","parameters":[{"name":"instanceId","required":true,"in":"path","schema":{"type":"string"}},{"name":"assignmentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"tags":["Hosting"]}},"/api/v1/runtime/v1/presence/heartbeat":{"post":{"operationId":"PlayerRuntimeController_heartbeat","parameters":[],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Refresh presence for the exact admitted player Runtime session.","tags":["Player Runtime"]}},"/api/v1/runtime/v1/presence/activity":{"post":{"operationId":"PlayerRuntimeController_setActivity","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimePresenceActivityDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Set bounded rich presence for the admitted player only.","tags":["Player Runtime"]},"delete":{"operationId":"PlayerRuntimeController_clearActivity","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Clear rich presence for the admitted player only.","tags":["Player Runtime"]}},"/api/v1/item-distributions":{"post":{"operationId":"ItemDistributionsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateItemDistributionRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Create a creator-authorized primary item distribution.","tags":["Item Distributions"]}},"/api/v1/item-distributions/creator":{"get":{"operationId":"ItemDistributionsController_listCreator","parameters":[{"name":"itemId","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List distributions owned by the current creator.","tags":["Item Distributions"]}},"/api/v1/item-distributions/{id}":{"patch":{"operationId":"ItemDistributionsController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateItemDistributionRequestDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Update mutable distribution policy.","tags":["Item Distributions"]}},"/api/v1/item-distributions/{id}/disable":{"post":{"operationId":"ItemDistributionsController_disable","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Disable a distribution without deleting its history.","tags":["Item Distributions"]}},"/api/v1/collectibles/offers/{offerId}/accept-capability":{"get":{"operationId":"OffersController_acceptCapability","parameters":[{"name":"offerId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"401":{"description":"Unauthorized."},"403":{"description":"Only the listing seller can inspect acceptance requirements"}},"security":[{"bearer":[]}],"summary":"Get server-authoritative seller requirements for accepting one exact offer","tags":["Collectible Offers"]}},"/api/v1/collectibles/offers/instant-buy":{"post":{"description":"Purchase a collectible instance from an active listing. Works with: 1) FIXED_PRICE listings (always available), 2) OFFER_BASED listings with allowInstantBuy=true (uses lixPrice as instant buy price). This will: 1) Create and escrow a transfer transaction, 2) Transfer ownership of the collectible instance to the buyer, 3) Complete the payment, 4) Mark the listing as SOLD, 5) Create a trade record, 6) Cancel and refund all pending offers (for OFFER_BASED listings). All operations are performed in a database transaction to ensure atomicity.","operationId":"OffersController_instantBuy","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstantBuyRequestDto"}}}},"responses":{"200":{"description":"Purchase completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectibleListingResponseDto"}}}},"400":{"description":"Listing not found, not active, instant buy not enabled, insufficient balance, or transaction failed. A home priced below its area-derived floor returns `code: \"home_below_price_floor\"` with `minPriceLix`."},"401":{"description":"Unauthorized."},"403":{"description":"Cannot buy your own listing"}},"security":[{"bearer":[]}],"summary":"Instantly purchase a FIXED_PRICE listing or OFFER_BASED listing with instant buy enabled","tags":["Collectible Offers"]}},"/api/v1/collectibles/offers/place-offer":{"post":{"description":"Place an offer on a collectible instance listed as OFFER_BASED. This will: 1) Check your wallet balance, 2) Create a pending transfer transaction, 3) Lock the offer amount in your wallet, 4) Create an offer record with PENDING status. The seller can then accept or reject your offer. You can only have one pending offer per listing.","operationId":"OffersController_placeOffer","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceOfferRequestDto"}}}},"responses":{"200":{"description":"Offer placed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectibleOfferResponseDto"}}}},"400":{"description":"Listing not found, not active, not OFFER_BASED, insufficient balance, offer too low, or already have pending offer. An offer below a home’s area-derived floor returns `code: \"home_below_price_floor\"` with `minPriceLix`."},"401":{"description":"Unauthorized."},"403":{"description":"Cannot make an offer on your own listing"}},"security":[{"bearer":[]}],"summary":"Place an offer on an OFFER_BASED listing","tags":["Collectible Offers"]}},"/api/v1/collectibles/offers/listings/{listingId}/offers":{"get":{"description":"Retrieve offers for a specific listing with pagination and optional filters. Supports filtering by status, userId (to get offers from a specific user), and optimized queries for highest/lowest single offers. Supports sorting by offer amount (low to high or high to low). Any authenticated user can view offers.","operationId":"OffersController_getListingOffers","parameters":[{"name":"listingId","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by offer status","schema":{"type":"string","enum":["PENDING","ACCEPTED","REJECTED","RELEASED","WITHDRAWN","EXPIRED"]}},{"name":"userId","required":false,"in":"query","description":"Filter offers by the user who made the offer (buyer)","schema":{"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","type":"string"}},{"name":"highest","required":false,"in":"query","description":"Return only the single highest offer for the listing","schema":{"default":false,"type":"boolean"}},{"name":"lowest","required":false,"in":"query","description":"Return only the single lowest offer for the listing","schema":{"default":false,"type":"boolean"}},{"name":"sortOrder","required":false,"in":"query","description":"Sort order for offers by price","schema":{"type":"string","enum":["low_to_high","high_to_low"]}}],"responses":{"200":{"description":"Offers retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCollectibleOfferResponseDto"}}}}},"400":{"description":"Listing not found or invalid query parameters"},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get offers for a listing","tags":["Collectible Offers"]}},"/api/v1/collectibles/offers/my-offers":{"get":{"description":"Retrieve all offers created by the authenticated user with pagination and optional filters (status, listing ID, collectible ID). Shows offers you have made on other sellers' listings.","operationId":"OffersController_getMyOffers","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by offer status","schema":{"example":"PENDING","type":"string","enum":["PENDING","ACCEPTED","REJECTED","RELEASED","WITHDRAWN","EXPIRED"]}},{"name":"listingId","required":false,"in":"query","description":"Filter by listing ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"collectibleId","required":false,"in":"query","description":"Filter by collectible ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}}],"responses":{"200":{"description":"Offers retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CollectibleOfferResponseDto"}}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get my offers","tags":["Collectible Offers"]}},"/api/v1/collectibles/offers/cancel-offer":{"post":{"description":"Cancel a pending offer you created. This will unlock/release the funds back to your wallet and set the offer status to WITHDRAWN. You can only cancel your own pending offers.","operationId":"OffersController_cancelOffer","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelOfferRequestDto"}}}},"responses":{"200":{"description":"Offer cancelled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectibleOfferResponseDto"}}}},"400":{"description":"Offer not found, not pending, or failed to unlock funds"},"401":{"description":"Unauthorized."},"403":{"description":"Only the offer creator can cancel the offer"}},"security":[{"bearer":[]}],"summary":"Cancel/withdraw your own offer","tags":["Collectible Offers"]}},"/api/v1/collectibles/offers/reject-offer":{"post":{"description":"Reject a pending offer on your listing. This will unlock the buyer's funds back to their wallet and set the offer status to REJECTED. Only the listing seller can reject offers.","operationId":"OffersController_rejectOffer","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectOfferRequestDto"}}}},"responses":{"200":{"description":"Offer rejected successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectibleOfferResponseDto"}}}},"400":{"description":"Offer not found, not pending, or failed to unlock funds"},"401":{"description":"Unauthorized."},"403":{"description":"Only the listing seller can reject offers"}},"security":[{"bearer":[]}],"summary":"Reject an offer on your listing (seller only)","tags":["Collectible Offers"]}},"/api/v1/collectibles/offers/accept-offer":{"post":{"description":"Accept a pending offer on your OFFER_BASED listing. This will: 1) Transfer the collectible to the buyer, 2) Complete the payment to the seller, 3) Mark the listing as SOLD, 4) Create a trade record, 5) Cancel all other pending offers on the listing (funds returned to buyers), 6) Mark the accepted offer as ACCEPTED. Only the listing seller can accept offers.","operationId":"OffersController_acceptOffer","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptOfferRequestDto"}}}},"responses":{"200":{"description":"Offer accepted successfully, collectible transferred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectibleOfferResponseDto"}}}},"400":{"description":"Offer not found, not pending, listing not active/offer-based, or payment failed. Accepting an offer below a home’s area-derived floor returns `code: \"home_below_price_floor\"`; the offer stays PENDING, so reject it to return the buyer’s funds."},"401":{"description":"Unauthorized."},"403":{"description":"Only the listing seller can accept offers"}},"security":[{"bearer":[]}],"summary":"Accept an offer on your listing (seller only)","tags":["Collectible Offers"]}},"/api/v1/marketplace/trust/verification-visibility":{"get":{"operationId":"MarketplaceTrustController_verificationVisibility","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationVisibilityResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get private verification eligibility and public-profile visibility opt-ins.","tags":["MarketplaceTrust"]},"patch":{"operationId":"MarketplaceTrustController_updateVerificationVisibility","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVerificationVisibilityRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationVisibilityResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Update public-profile verification claims. A claim can only be enabled after authoritative eligibility exists.","tags":["MarketplaceTrust"]}},"/api/v1/marketplace/trust/capabilities/resell-collectible":{"get":{"operationId":"MarketplaceTrustController_capability","parameters":[{"name":"priceLix","required":true,"in":"query","schema":{"type":"string"}},{"name":"collectibleInstanceId","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Read-side resale eligibility for the Verified checklist and the CH-1671-followup primary/secondary supply gate. Pass collectibleInstanceId when known — without it, the item cooldown and primary-supply checks cannot be evaluated and are reported clear by default (same \"cannot evaluate, don't block\" contract used elsewhere in this checklist).","tags":["MarketplaceTrust"]}},"/api/v1/marketplace/trust/phone/start":{"post":{"operationId":"MarketplaceTrustController_start","parameters":[],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"tags":["MarketplaceTrust"]}},"/api/v1/marketplace/trust/phone/check":{"post":{"operationId":"MarketplaceTrustController_check","parameters":[],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"tags":["MarketplaceTrust"]}},"/api/v1/payment/create-pending-purchase":{"post":{"description":"Client tokens are not allowed on this route: Making payments with client tokens is not supported.","operationId":"PaymentController_createPendingPurchase","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePendingPurchaseDto"}}}},"responses":{"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"tags":["Payment","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: Making payments with client tokens is not supported."}}},"/api/v1/payment/create-embedded-session":{"post":{"description":"Client tokens are not allowed on this route: Making payments with client tokens is not supported.","operationId":"PaymentController_createEmbeddedSession","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmbeddedSessionDto"}}}},"responses":{"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"tags":["Payment","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: Making payments with client tokens is not supported."}}},"/api/v1/payment/session-status/{sessionId}":{"post":{"operationId":"PaymentController_getSessionStatus","parameters":[{"name":"sessionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Payment"]}},"/api/v1/payment/confirm-payment":{"post":{"description":"Client tokens are not allowed on this route: Making payments with client tokens is not supported.","operationId":"PaymentController_confirmPayment","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmPaymentDto"}}}},"responses":{"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"tags":["Payment","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: Making payments with client tokens is not supported."}}},"/api/v1/payment/purchase-lix-bundle":{"post":{"description":"Client tokens are not allowed on this route: Making payments with client tokens is not supported.","operationId":"PaymentController_purchaseLIXBundle","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseLIXBundleDto"}}}},"responses":{"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"tags":["Payment","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: Making payments with client tokens is not supported."}}},"/api/v1/payment/methods":{"get":{"operationId":"PaymentController_listPaymentMethods","parameters":[],"responses":{"200":{"description":""}},"tags":["Payment"]}},"/api/v1/payment/methods/setup-intent":{"post":{"operationId":"PaymentController_createSetupIntent","parameters":[],"responses":{"201":{"description":""}},"tags":["Payment"]}},"/api/v1/payment/methods/{paymentMethodId}/default":{"post":{"operationId":"PaymentController_setDefaultPaymentMethod","parameters":[{"name":"paymentMethodId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"tags":["Payment"]}},"/api/v1/payment/methods/{paymentMethodId}":{"delete":{"operationId":"PaymentController_deletePaymentMethod","parameters":[{"name":"paymentMethodId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Payment"]}},"/api/v1/payment/regenerate-session/{transactionId}":{"post":{"description":"Client tokens are not allowed on this route: Making payments with client tokens is not supported.","operationId":"PaymentController_regenerateSession","parameters":[{"name":"transactionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"tags":["Payment","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: Making payments with client tokens is not supported."}}},"/api/v1/payment/webhook":{"post":{"operationId":"PaymentController_handleWebhook","parameters":[{"name":"stripe-signature","required":true,"in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["Payment"]}},"/api/v1/lix-bundles":{"get":{"description":"Public endpoint to retrieve available LIX bundles with filtering and sorting options. By default, returns active bundles ordered by displayOrder. Supports pagination and various filters including price range, LIX amount, and discount availability.","operationId":"LixBundlesController_getBundles","parameters":[{"name":"name","required":false,"in":"query","description":"Filter by bundle name (partial match, case-insensitive)","schema":{"example":"Starter","type":"string"}},{"name":"isActive","required":false,"in":"query","description":"Filter by active status","schema":{"example":true,"type":"boolean"}},{"name":"minLixAmount","required":false,"in":"query","description":"Minimum LIX amount","schema":{"example":100,"type":"number"}},{"name":"maxLixAmount","required":false,"in":"query","description":"Maximum LIX amount","schema":{"example":10000,"type":"number"}},{"name":"minFixedPrice","required":false,"in":"query","description":"Minimum fixed price in cents","schema":{"example":500,"type":"number"}},{"name":"maxFixedPrice","required":false,"in":"query","description":"Maximum fixed price in cents","schema":{"example":5000,"type":"number"}},{"name":"hasDiscount","required":false,"in":"query","description":"Filter bundles with discount","schema":{"example":true,"type":"boolean"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by","schema":{"default":"displayOrder","type":"string","enum":["name","lixAmount","fixedPrice","discountPercentage","displayOrder","createdAt","updatedAt","isActive","deletedAt"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of bundles to retrieve per page","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LixBundleResponseDto"}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"Get available LIX bundles","tags":["LIX Bundles"]}},"/api/v1/lix-bundles/admin":{"post":{"description":"Admin-only endpoint to create a new LIX bundle. Must specify either a fixed price or discount percentage (or both). The bundle will be available for purchase based on the isActive flag.","operationId":"LixBundlesController_createBundle","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLixBundleDto"}}}},"responses":{"201":{"description":"LIX bundle created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LixBundleResponseDto"}}}},"400":{"description":"Invalid request data or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Create a new LIX bundle","tags":["LIX Bundles"]},"get":{"description":"Admin-only endpoint to retrieve all LIX bundles with filtering and sorting options. Unlike the public endpoint, this includes soft-deleted bundles and supports filtering by deletedAt. Supports all the same filters as the public endpoint plus access to deleted records.","operationId":"LixBundlesController_getAllBundlesAdmin","parameters":[{"name":"name","required":false,"in":"query","description":"Filter by bundle name (partial match, case-insensitive)","schema":{"example":"Starter","type":"string"}},{"name":"isActive","required":false,"in":"query","description":"Filter by active status","schema":{"example":true,"type":"boolean"}},{"name":"minLixAmount","required":false,"in":"query","description":"Minimum LIX amount","schema":{"example":100,"type":"number"}},{"name":"maxLixAmount","required":false,"in":"query","description":"Maximum LIX amount","schema":{"example":10000,"type":"number"}},{"name":"minFixedPrice","required":false,"in":"query","description":"Minimum fixed price in cents","schema":{"example":500,"type":"number"}},{"name":"maxFixedPrice","required":false,"in":"query","description":"Maximum fixed price in cents","schema":{"example":5000,"type":"number"}},{"name":"hasDiscount","required":false,"in":"query","description":"Filter bundles with discount","schema":{"example":true,"type":"boolean"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by","schema":{"default":"displayOrder","type":"string","enum":["name","lixAmount","fixedPrice","discountPercentage","displayOrder","createdAt","updatedAt","isActive","deletedAt"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of bundles to retrieve per page","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LixBundleResponseDto"}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get all LIX bundles including soft-deleted","tags":["LIX Bundles"]}},"/api/v1/lix-bundles/admin/{id}":{"patch":{"description":"Admin-only endpoint to update an existing LIX bundle. All fields are optional. If updating pricing, ensure at least one pricing method (fixedPrice or discountPercentage) remains set.","operationId":"LixBundlesController_updateBundle","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLixBundleDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/LixBundleResponseDto"}}}}}},"400":{"description":"Invalid request data or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"LIX bundle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update a LIX bundle","tags":["LIX Bundles"]},"delete":{"description":"Admin-only endpoint to soft delete a LIX bundle. The bundle will be marked as deleted and will no longer appear in listings, but historical data is preserved.","operationId":"LixBundlesController_deleteBundle","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/LixBundleResponseDto"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"LIX bundle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Delete a LIX bundle","tags":["LIX Bundles"]},"get":{"description":"Admin-only endpoint to retrieve a specific LIX bundle by its ID. Returns full bundle details.","operationId":"LixBundlesController_getBundle","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/LixBundleResponseDto"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"LIX bundle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get a LIX bundle by ID","tags":["LIX Bundles"]}},"/api/v1/transactions/me":{"get":{"description":"Retrieves a paginated list of transactions for the currently authenticated user. Supports filtering by status and direction.","operationId":"TransactionsController_getMyTransactions","parameters":[{"name":"status","required":false,"in":"query","description":"Filter by transaction status (supports multiple)","schema":{"example":["completed"],"type":"array","items":{"type":"string","enum":["pending","completed","failed","reverted","expired","locked","offer_locked"]}}},{"name":"direction","required":false,"in":"query","description":"Filter by transaction direction","schema":{"example":"incoming","type":"string","enum":["incoming","outgoing"]}},{"name":"type","required":false,"in":"query","description":"Filter by transaction type (supports multiple)","schema":{"example":["transfer"],"type":"array","items":{"type":"string","enum":["purchase","transfer","credit","refund","fee","payout","issuance","instant_hosting"]}}},{"name":"excludeTypes","required":false,"in":"query","description":"Exclude specific transaction types from results (supports multiple)","schema":{"example":["purchase","fee"],"type":"array","items":{"type":"string","enum":["purchase","transfer","credit","refund","fee","payout","issuance","instant_hosting"]}}},{"name":"excludeStatuses","required":false,"in":"query","description":"Exclude specific transaction statuses from results (supports multiple)","schema":{"example":["expired","failed"],"type":"array","items":{"type":"string","enum":["pending","completed","failed","reverted","expired","locked","offer_locked"]}}},{"name":"page","required":false,"in":"query","description":"Page number for pagination","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"default":10,"example":10,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TransactionCollectionResponseDto"}}}}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get transactions for the authenticated user","tags":["Transactions"]}},"/api/v1/transactions/me/detailed":{"get":{"description":"Retrieves a paginated list of transactions with related order or collectible offer details populated. Purchase and issuance transactions do not include extra details.","operationId":"TransactionsController_getMyTransactionsDetailed","parameters":[{"name":"status","required":false,"in":"query","description":"Filter by transaction status (supports multiple)","schema":{"example":["completed"],"type":"array","items":{"type":"string","enum":["pending","completed","failed","reverted","expired","locked","offer_locked"]}}},{"name":"direction","required":false,"in":"query","description":"Filter by transaction direction","schema":{"example":"incoming","type":"string","enum":["incoming","outgoing"]}},{"name":"type","required":false,"in":"query","description":"Filter by transaction type (supports multiple)","schema":{"example":["transfer"],"type":"array","items":{"type":"string","enum":["purchase","transfer","credit","refund","fee","payout","issuance","instant_hosting"]}}},{"name":"excludeTypes","required":false,"in":"query","description":"Exclude specific transaction types from results (supports multiple)","schema":{"example":["purchase","fee"],"type":"array","items":{"type":"string","enum":["purchase","transfer","credit","refund","fee","payout","issuance","instant_hosting"]}}},{"name":"excludeStatuses","required":false,"in":"query","description":"Exclude specific transaction statuses from results (supports multiple)","schema":{"example":["expired","failed"],"type":"array","items":{"type":"string","enum":["pending","completed","failed","reverted","expired","locked","offer_locked"]}}},{"name":"page","required":false,"in":"query","description":"Page number for pagination","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"default":10,"example":10,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TransactionDetailedResponseDto"}}}}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get detailed transactions for the authenticated user","tags":["Transactions"]}},"/api/v1/transactions/me/pending-funds":{"get":{"description":"Retrieves a paginated list of pending funds that will become withdrawable when they mature. These are funds from transactions that have a maturity period.","operationId":"TransactionsController_getMyPendingFunds","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"example":10,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PendingMaturityDto"}}}}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get pending funds for the authenticated user","tags":["Transactions"]}},"/api/v1/world-item/{packageId}":{"post":{"operationId":"WorldItemController_create","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorldItemRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CreateWorldItemResponseDto"}}}}}},"400":{"description":"Failed to create world item."},"401":{"description":"Unauthorized."},"403":{"description":"You are not allowed to create items for this package."},"404":{"description":"Package not found."},"409":{"description":"World item slug already exists for this package."}},"security":[{"bearer":[]}],"summary":"Create a new world item.","tags":["WorldItem"]},"get":{"operationId":"WorldItemController_retrieveAll","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}},{"name":"name","required":false,"in":"query","description":"The name of the world item to search for.","schema":{"type":"string"}},{"name":"slug","required":false,"in":"query","description":"The slug of the world item to search for.","schema":{"type":"string"}},{"name":"available","required":false,"in":"query","description":"Filter by availability status.","schema":{"type":"boolean"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorldItemResponseDto"}}}}}}},"400":{"description":"Invalid request parameters."},"401":{"description":"Unauthorized."},"404":{"description":"Package not found."}},"security":[{"bearer":[]}],"summary":"Get all world items for a package with pagination and search.","tags":["WorldItem"]},"delete":{"operationId":"WorldItemController_deleteMany","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteWorldItemsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/DeleteWorldItemsResponseDto"}}}}}},"400":{"description":"Failed to delete world items."},"401":{"description":"Unauthorized."},"403":{"description":"You are not allowed to delete items for this package."},"404":{"description":"Package not found."}},"security":[{"bearer":[]}],"summary":"Delete multiple world items by IDs within package scope.","tags":["WorldItem"]}},"/api/v1/world-item/{packageId}/{worldItemId}":{"get":{"operationId":"WorldItemController_retrieveOne","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}},{"name":"worldItemId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/WorldItemResponseDto"}}}}}},"400":{"description":"Invalid world item ID format."},"401":{"description":"Unauthorized."},"404":{"description":"Package not found."}},"security":[{"bearer":[]}],"summary":"Get a single world item by ID within package scope.","tags":["WorldItem"]},"patch":{"operationId":"WorldItemController_update","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}},{"name":"worldItemId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorldItemRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/WorldItemResponseDto"}}}}}},"400":{"description":"Failed to update world item."},"401":{"description":"Unauthorized."},"403":{"description":"You are not allowed to update items for this package."},"404":{"description":"Package not found."}},"security":[{"bearer":[]}],"summary":"Update a world item by ID within package scope.","tags":["WorldItem"]},"delete":{"operationId":"WorldItemController_deleteOne","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}},{"name":"worldItemId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/DeleteWorldItemResponseDto"}}}}}},"400":{"description":"Failed to delete world item."},"401":{"description":"Unauthorized."},"403":{"description":"You are not allowed to delete items for this package."},"404":{"description":"Package not found."}},"security":[{"bearer":[]}],"summary":"Delete a single world item by ID within package scope.","tags":["WorldItem"]}},"/api/v1/world-item/{packageId}/{worldItemId}/confirm-thumbnail":{"post":{"description":"Call this AFTER uploading the thumbnail via the presigned URL. The object is re-fetched from R2 and run through the shared moderation gate; if rejected it is deleted and the request fails with 422. Only the package owner may confirm.","operationId":"WorldItemController_confirmThumbnail","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}},{"name":"worldItemId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/WorldItemResponseDto"}}}}}},"401":{"description":"Unauthorized."},"403":{"description":"You are not allowed to update items for this package."},"404":{"description":"Package not found."}},"security":[{"bearer":[]}],"summary":"Confirm & moderate an uploaded world item thumbnail.","tags":["WorldItem"]}},"/api/v1/public/users/check-username/{username}":{"get":{"operationId":"PublicUsersController_checkUsernameAvailability","parameters":[{"name":"username","required":true,"in":"path","description":"The username to check availability for.","schema":{"example":"exampleuser1","type":"string"}}],"responses":{"200":{"description":"Username availability status.","content":{"application/json":{"schema":{"type":"object","properties":{"available":{"type":"boolean"}}}}}}},"summary":"Check if a username is available.","tags":["PublicUsers"]}},"/api/v1/public/users/{userId}":{"get":{"operationId":"PublicUsersController_getUser","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PublicUserProfileResponseDto"}}}}}},"404":{"description":"User not found."}},"summary":"Retrieve minimal public info about a user by ID.","tags":["PublicUsers"]}},"/api/v1/public/packages":{"get":{"operationId":"PublicPackagesController_list","parameters":[{"name":"name","required":false,"in":"query","description":"The name of the package to search for.","schema":{"type":"string"}},{"name":"slug","required":false,"in":"query","description":"The slug of the package to search for.","schema":{"type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"The ID of the creator to search for.","schema":{"type":"string"}},{"name":"showOnlyPrivate","required":false,"in":"query","description":"Show only private packages that the authenticated user has access to (either as owner or via role-granted access). Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"hideMine","required":false,"in":"query","description":"Hide packages created by the authenticated user. Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"type","required":false,"in":"query","description":"The package types to search for.","schema":{"type":"array","items":{"type":"string","enum":["World","Map","QRE","Vehicle","Character","Character Preset","Weapon","Wearable","Animation","Structure","Interior","Tool","Effect","Sound","Script","Addon","EDL","Other"]}}},{"name":"excludeType","required":false,"in":"query","description":"The package types to exclude from the search.","schema":{"type":"array","items":{"type":"string","enum":["World","Map","QRE","Vehicle","Character","Character Preset","Weapon","Wearable","Animation","Structure","Interior","Tool","Effect","Sound","Script","Addon","EDL","Other"]}}},{"name":"contentRating","required":false,"in":"query","description":"The content rating of the package to search for.","schema":{"type":"string","enum":["Everyone","Teen","Mature","Adult"]}},{"name":"tags","required":false,"in":"query","description":"The tags of the package to search for.","schema":{"type":"array","items":{"type":"string"}}},{"name":"publishedAfter","required":false,"in":"query","description":"The date to search for packages published after.","schema":{"format":"date-time","type":"string"}},{"name":"publishedBefore","required":false,"in":"query","description":"The date to search for packages published before.","schema":{"format":"date-time","type":"string"}},{"name":"updatedAfter","required":false,"in":"query","description":"The date to search for packages updated after.","schema":{"format":"date-time","type":"string"}},{"name":"updatedBefore","required":false,"in":"query","description":"The date to search for packages updated before.","schema":{"format":"date-time","type":"string"}},{"name":"lastReleaseAfter","required":false,"in":"query","description":"The date to search for packages with latest release after this date.","schema":{"format":"date-time","type":"string"}},{"name":"lastReleaseBefore","required":false,"in":"query","description":"The date to search for packages with latest release before this date.","schema":{"format":"date-time","type":"string"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by.","schema":{"type":"string","enum":["name","slug","createdAt","updatedAt","publishedAt","lastReleaseAt"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in.","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of servers to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPackageCollectionResponseDto"}}}},"400":{"description":"The request query is invalid."}},"summary":"Get all public packages with sanitized fields.","tags":["PublicPackages"]}},"/api/v1/public/packages/{packageId}":{"get":{"operationId":"PublicPackagesController_getOne","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPackageResponseDto"}}}},"404":{"description":"Package not found."}},"summary":"Get a single public package by ID with sanitized fields.","tags":["PublicPackages"]}},"/api/v1/public/packages/{packageId}/reviews":{"get":{"description":"Returns the aggregate thumbs up/down counts and percentage plus a paginated list of reviews for the specified package. Read-only: no authentication required and no per-user vote is included.","operationId":"PublicPackagesController_getPackageReviews","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Limit (items per page)","schema":{"default":10,"example":10,"type":"number"}}],"responses":{"200":{"description":"Public aggregate ratings + paginated reviews.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserReviewsWithThumbsResponseDto"}}}},"400":{"description":"Invalid packageId format. Must be a valid UUID."},"404":{"description":"Package not found."}},"summary":"Get the public ratings/reviews for a package (unauthenticated).","tags":["PublicPackages"]}},"/api/v1/public/packages/{packageId}/versions":{"get":{"description":"Returns the published version list for a public package. Private packages return 404. Read-only: no authentication required.","operationId":"PublicPackagesController_getPackageVersions","parameters":[{"name":"packageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PackageVersionResponseDto"}}}}},"400":{"description":"Invalid packageId format. Must be a valid UUID."},"404":{"description":"Package not found."}},"summary":"Get a public package's version history (unauthenticated).","tags":["PublicPackages"]}},"/api/v1/public/servers":{"get":{"operationId":"PublicServersController_list","parameters":[{"name":"name","required":false,"in":"query","description":"The name of the server to search for.","schema":{"type":"string"}},{"name":"slug","required":false,"in":"query","description":"The slug of the server to search for.","schema":{"type":"string"}},{"name":"ownerId","required":false,"in":"query","description":"The ID of the owner to search for.","schema":{"type":"string"}},{"name":"gameMode","required":false,"in":"query","description":"The game mode to search for.","schema":{"type":"array","items":{"type":"string","enum":["Sandbox","Roleplay","Survival","Free For All","Team Deathmatch","Capture The Flag","Social"]}}},{"name":"hostingType","required":false,"in":"query","description":"The hosting type to search for.","schema":{"type":"array","items":{"type":"string","enum":["Dedicated","Local","Provisioned"]}}},{"name":"contentRating","required":false,"in":"query","description":"The content rating to search for.","schema":{"type":"array","items":{"type":"string","enum":["Everyone","Teen","Mature","Adult"]}}},{"name":"tags","required":false,"in":"query","description":"The tags to search for.","schema":{"type":"array","items":{"type":"string"}}},{"name":"publishedAfter","required":false,"in":"query","description":"The date to search for servers published after.","schema":{"format":"date-time","type":"string"}},{"name":"publishedBefore","required":false,"in":"query","description":"The date to search for servers published before.","schema":{"format":"date-time","type":"string"}},{"name":"updatedAfter","required":false,"in":"query","description":"The date to search for servers updated after.","schema":{"format":"date-time","type":"string"}},{"name":"updatedBefore","required":false,"in":"query","description":"The date to search for servers updated before.","schema":{"format":"date-time","type":"string"}},{"name":"packageId","required":false,"in":"query","description":"The package ID to search for servers that use any version of this package.","schema":{"type":"string"}},{"name":"packageVersionId","required":false,"in":"query","description":"The package version ID to search for servers that use this specific package version (either as worldId or in packageVersions).","schema":{"type":"string"}},{"name":"showOnlyPrivate","required":false,"in":"query","description":"Show only private servers that the authenticated user has access to (either as owner or whitelisted). Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"hideMine","required":false,"in":"query","description":"Hide servers owned by the authenticated user. Only works when user is authenticated.","schema":{"default":false,"type":"boolean"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by.","schema":{"type":"string","enum":["name","slug","currentPlayers","visits","createdAt","updatedAt","publishedAt"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in.","schema":{"type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of servers to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicServerResponseDto"}}}}},"400":{"description":"The request query is invalid."}},"summary":"Get all public servers with sanitized fields (no IPs/secrets).","tags":["PublicServers"]}},"/api/v1/public/servers/{serverId}":{"get":{"operationId":"PublicServersController_getOne","parameters":[{"name":"serverId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicServerResponseDto"}}}},"404":{"description":"Server not found."}},"summary":"Get a single public server by ID with sanitized fields.","tags":["PublicServers"]}},"/api/v1/public/collectibles/brands":{"get":{"description":"Retrieve collectible brands with optional filters: slug (exact match), name (exact match), searchString (searches slug, name, and description). Supports pagination. Public endpoint - no authentication required.","operationId":"PublicCollectibleBrandsController_retrieveAll","parameters":[{"name":"slug","required":false,"in":"query","description":"Filter by exact slug match","schema":{"example":"luxury-motors","type":"string"}},{"name":"name","required":false,"in":"query","description":"Filter by exact name match","schema":{"example":"Luxury Motors","type":"string"}},{"name":"searchString","required":false,"in":"query","description":"Universal search string that searches in slug, name, and description (partial match, case-insensitive)","schema":{"example":"luxury automotive","type":"string"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of brands to retrieve per page","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CollectibleBrandResponseDto"}}}}}}},"400":{"description":"Invalid query parameters."}},"summary":"Get all collectible brands (public)","tags":["Public Collectible Brands"]}},"/api/v1/public/collectibles/brands/{brandId}":{"get":{"description":"Retrieve a specific collectible brand with creator info. Public endpoint - no authentication required.","operationId":"PublicCollectibleBrandsController_retrieveOne","parameters":[{"name":"brandId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CollectibleBrandResponseDto"}}}}}},"404":{"description":"Brand not found."}},"summary":"Get a single collectible brand by ID (public)","tags":["Public Collectible Brands"]}},"/api/v1/public/collectibles":{"get":{"description":"Retrieve collectibles with optional filters: id, slug, name search, searchString (searches name and description), type, onlyUniversal, and compatibleWith (package slug). Supports pagination. Does not include instances - use dedicated endpoint to fetch instances. Does not include presigned upload URLs.","operationId":"PublicCollectiblesController_list","parameters":[{"name":"id","required":false,"in":"query","description":"Filter by collectible ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"slug","required":false,"in":"query","description":"Filter by exact slug match","schema":{"example":"ferrari-488","type":"string"}},{"name":"name","required":false,"in":"query","description":"Search by name (partial match, case-insensitive)","schema":{"example":"Ferrari","type":"string"}},{"name":"searchString","required":false,"in":"query","description":"Search string that searches in both name and description (partial match, case-insensitive)","schema":{"example":"luxury sports car","type":"string"}},{"name":"type","required":false,"in":"query","description":"Filter by collectible type","schema":{"example":"Vehicle","type":"string","enum":["Wearable","Placeable","Vehicle","Clothing","Accessory","Character","HomeItem","Property"]}},{"name":"onlyUniversal","required":false,"in":"query","description":"Filter to only universal collectibles (works across all packages)","schema":{"example":true,"type":"boolean"}},{"name":"compatibleWith","required":false,"in":"query","description":"Filter collectibles compatible with a specific package slug (includes universal collectibles)","schema":{"example":"my-game-package","type":"string"}},{"name":"brandId","required":false,"in":"query","description":"Filter by brand ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"brandSlug","required":false,"in":"query","description":"Filter by brand slug","schema":{"example":"luxury-motors","type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"Filter by creator ID (user who created the collectible)","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Field to sort by","schema":{"example":"createdAt","type":"string","enum":["name_asc","name_desc","createdAt","updatedAt","lastSaleAt","supply_asc","supply_desc","lastSalePrice","totalSalesCount","totalVolumeTraded","allTimeHighPrice","avgSalePrice"]}},{"name":"sortOrder","required":false,"in":"query","description":"Sort order direction (ASC or DESC)","schema":{"default":"DESC","example":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"minLastSalePrice","required":false,"in":"query","description":"Filter collectibles with last sale price greater than this value","schema":{"example":100,"type":"number"}},{"name":"maxLastSalePrice","required":false,"in":"query","description":"Filter collectibles with last sale price less than this value","schema":{"example":1000,"type":"number"}},{"name":"minAvgSalePrice","required":false,"in":"query","description":"Filter collectibles with average sale price greater than this value","schema":{"example":100,"type":"number"}},{"name":"maxAvgSalePrice","required":false,"in":"query","description":"Filter collectibles with average sale price less than this value","schema":{"example":1000,"type":"number"}},{"name":"minAllTimeHighPrice","required":false,"in":"query","description":"Filter collectibles with all-time high price greater than this value","schema":{"example":100,"type":"number"}},{"name":"maxAllTimeHighPrice","required":false,"in":"query","description":"Filter collectibles with all-time high price less than this value","schema":{"example":1000,"type":"number"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of collectibles to retrieve per page","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCollectibleResponseDto"}}}}},"400":{"description":"The request query is invalid."}},"summary":"Get all public collectibles with sanitized fields.","tags":["Public Collectibles"]}},"/api/v1/public/collectibles/{collectibleId}":{"get":{"description":"Retrieve a specific collectible with creator info and compatible packages. Does not include instances - use dedicated endpoint to fetch instances. Does not include presigned upload URLs.","operationId":"PublicCollectiblesController_getOne","parameters":[{"name":"collectibleId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCollectibleResponseDto"}}}},"404":{"description":"Collectible not found."}},"summary":"Get a single public collectible by ID with sanitized fields.","tags":["Public Collectibles"]}},"/api/v1/public/collectibles/{collectibleId}/instances":{"get":{"description":"Retrieve paginated instances for a specific collectible with optional filters: ownerId, serial, isTransferable, isLocked (marketplace status), locationType. Ordered by serial number. Does not include presigned upload URLs.","operationId":"PublicCollectiblesController_retrieveCollectibleInstances","parameters":[{"name":"collectibleId","required":true,"in":"path","schema":{"type":"string"}},{"name":"ownerId","required":false,"in":"query","description":"Filter by owner ID","schema":{"example":"user-uuid-123","type":"string"}},{"name":"serial","required":false,"in":"query","description":"Filter by serial number","schema":{"example":1,"type":"number"}},{"name":"isTransferable","required":false,"in":"query","description":"Filter by transferability","schema":{"example":true,"type":"boolean"}},{"name":"isLocked","required":false,"in":"query","description":"Filter by lock status (true = locked/listed, false = available)","schema":{"example":false,"type":"boolean"}},{"name":"locationType","required":false,"in":"query","description":"Filter by location type","schema":{"example":"user","type":"string"}},{"name":"page","required":true,"in":"query","description":"Page number for pagination","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCollectibleInstanceResponseDto"}}}}},"400":{"description":"Invalid query parameters."},"404":{"description":"Collectible not found."}},"summary":"Get public instances for a collectible","tags":["Public Collectibles"]}},"/api/v1/public/collectibles/listings/all":{"get":{"description":"Retrieve all marketplace listings with pagination and optional filters (status, listing type, collectible ID, slug, seller ID). This is a public endpoint that can be accessed without authentication.","operationId":"PublicCollectibleListingsController_getAllListings","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by listing status","schema":{"example":"ACTIVE","type":"string","enum":["ACTIVE","SOLD","CANCELLED"]}},{"name":"listingType","required":false,"in":"query","description":"Filter by listing type","schema":{"example":"FIXED_PRICE","type":"string","enum":["FIXED_PRICE","OFFER_BASED"]}},{"name":"collectibleInstanceId","required":false,"in":"query","description":"Filter by collectible instance ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"collectibleId","required":false,"in":"query","description":"Filter by collectible ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"slug","required":false,"in":"query","description":"Filter by collectible slug","schema":{"example":"rare-spaceship","type":"string"}},{"name":"sellerId","required":false,"in":"query","description":"Filter by seller user ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"type","required":false,"in":"query","description":"Filter by collectible type","schema":{"example":"Wearable","type":"string","enum":["Wearable","Placeable","Vehicle","Clothing","Accessory","Character","HomeItem","Property"]}},{"name":"brandId","required":false,"in":"query","description":"Filter by brand ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"brandSlug","required":false,"in":"query","description":"Filter by brand slug","schema":{"example":"acme-corp","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort listings by specific criteria","schema":{"example":"price_low_to_high","type":"string","enum":["price_low_to_high","price_high_to_low","newest","name_a_z","name_z_a"]}},{"name":"minPrice","required":false,"in":"query","description":"Minimum price filter (in LIX)","schema":{"minimum":0,"example":10,"type":"number"}},{"name":"maxPrice","required":false,"in":"query","description":"Maximum price filter (in LIX)","schema":{"minimum":0,"example":1000,"type":"number"}}],"responses":{"200":{"description":"Listings retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCollectibleListingResponseDto"}}}}},"400":{"description":"Invalid query parameters"}},"summary":"Get all public marketplace listings","tags":["Public Collectible Listings"]}},"/api/v1/public/collectibles/trades/instance":{"get":{"description":"Retrieve complete trade history for a specific collectible instance with pagination and filtering options. Supports filtering by trade type and time period (start/end dates). Useful for analyzing price trends, market activity, and trade volume. Does not include sensitive user IDs, transaction IDs, or fee information.","operationId":"PublicCollectibleTradesController_getInstanceTrades","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"instanceId","required":true,"in":"query","description":"The UUID of the collectible instance","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"tradeType","required":false,"in":"query","description":"Filter by trade type","schema":{"example":"INSTANT_BUY","type":"string","enum":["INSTANT_BUY","OFFER_ACCEPTED"]}},{"name":"startDate","required":false,"in":"query","description":"Filter trades from this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter trades until this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"buyerId","required":false,"in":"query","description":"Filter by buyer user ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"sellerId","required":false,"in":"query","description":"Filter by seller user ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"minPrice","required":false,"in":"query","description":"Filter by minimum trade price (LIX)","schema":{"example":50,"type":"number"}},{"name":"maxPrice","required":false,"in":"query","description":"Filter by maximum trade price (LIX)","schema":{"example":500,"type":"number"}}],"responses":{"200":{"description":"Trade history retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCollectibleTradeResponseDto"}}}}},"400":{"description":"Invalid query parameters"},"404":{"description":"Instance not found"}},"summary":"Get public historical trades for a collectible instance","tags":["Public Collectible Trades"]}},"/api/v1/public/collectibles/trades/collectible":{"get":{"description":"Retrieve complete trade history for all instances of a specific collectible with pagination and filtering options. Supports filtering by trade type and time period (start/end dates). Useful for analyzing overall collectible market trends, total trading volume, and price history across all instances. Does not include sensitive user IDs, transaction IDs, or fee information.","operationId":"PublicCollectibleTradesController_getCollectibleTrades","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"collectibleId","required":true,"in":"query","description":"The UUID of the collectible","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"tradeType","required":false,"in":"query","description":"Filter by trade type","schema":{"example":"INSTANT_BUY","type":"string","enum":["INSTANT_BUY","OFFER_ACCEPTED"]}},{"name":"startDate","required":false,"in":"query","description":"Filter trades from this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter trades until this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"buyerId","required":false,"in":"query","description":"Filter by buyer user ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"sellerId","required":false,"in":"query","description":"Filter by seller user ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"minPrice","required":false,"in":"query","description":"Filter by minimum trade price (LIX)","schema":{"example":50,"type":"number"}},{"name":"maxPrice","required":false,"in":"query","description":"Filter by maximum trade price (LIX)","schema":{"example":500,"type":"number"}}],"responses":{"200":{"description":"Trade history retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCollectibleTradeResponseDto"}}}}},"400":{"description":"Invalid query parameters"},"404":{"description":"Collectible not found"}},"summary":"Get public historical trades for all instances of a collectible","tags":["Public Collectible Trades"]}},"/api/v1/public/collectibles/trades/user":{"get":{"description":"Retrieve complete trade history for a specific user with pagination and filtering options. Returns trades where the user was either buyer or seller. Supports filtering by showOnlySales, showOnlyBuys, trade type, price range (min/max), and time period (start/end dates). Does not include sensitive user IDs, transaction IDs, or fee information.","operationId":"PublicCollectibleTradesController_getUserTrades","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"userId","required":true,"in":"query","description":"The UUID of the user","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"showOnlySales","required":false,"in":"query","description":"Show only sales (user as seller)","schema":{"example":true,"type":"boolean"}},{"name":"showOnlyBuys","required":false,"in":"query","description":"Show only buys (user as buyer)","schema":{"example":true,"type":"boolean"}},{"name":"tradeType","required":false,"in":"query","description":"Filter by trade type","schema":{"example":"INSTANT_BUY","type":"string","enum":["INSTANT_BUY","OFFER_ACCEPTED"]}},{"name":"startDate","required":false,"in":"query","description":"Filter trades from this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter trades until this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"minPrice","required":false,"in":"query","description":"Filter by minimum trade price (LIX)","schema":{"example":50,"type":"number"}},{"name":"maxPrice","required":false,"in":"query","description":"Filter by maximum trade price (LIX)","schema":{"example":500,"type":"number"}}],"responses":{"200":{"description":"Trade history retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCollectibleTradeResponseDto"}}}}},"400":{"description":"Invalid query parameters"},"404":{"description":"User not found"}},"summary":"Get public historical trades for a user","tags":["Public Collectible Trades"]}},"/api/v1/public/collectibles/offers/listings/{listingId}/offers":{"get":{"description":"Retrieve offers for a specific listing with pagination and optional filters. Supports filtering by status, userId (to get offers from a specific user), and optimized queries for highest/lowest single offers. Supports sorting by offer amount (low to high or high to low). This is a public endpoint that can be accessed without authentication.","operationId":"PublicCollectibleOffersController_getListingOffers","parameters":[{"name":"listingId","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by offer status","schema":{"type":"string","enum":["PENDING","ACCEPTED","REJECTED","RELEASED","WITHDRAWN","EXPIRED"]}},{"name":"userId","required":false,"in":"query","description":"Filter offers by the user who made the offer (buyer)","schema":{"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","type":"string"}},{"name":"highest","required":false,"in":"query","description":"Return only the single highest offer for the listing","schema":{"default":false,"type":"boolean"}},{"name":"lowest","required":false,"in":"query","description":"Return only the single lowest offer for the listing","schema":{"default":false,"type":"boolean"}},{"name":"sortOrder","required":false,"in":"query","description":"Sort order for offers by price","schema":{"type":"string","enum":["low_to_high","high_to_low"]}}],"responses":{"200":{"description":"Offers retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCollectibleOfferResponseDto"}}}}},"400":{"description":"Listing not found or invalid query parameters"}},"summary":"Get offers for a listing (public)","tags":["Public Collectible Offers"]}},"/api/v1/public/universal-items":{"get":{"operationId":"PublicUniversalItemsController_list","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUniversalItemsResponseDto"}}}}},"summary":"Experimental prototype endpoint for public Universal Avatar Items.","tags":["PublicUniversalItems"]}},"/api/v1/collectibles/brands":{"post":{"description":"Creates a new collectible brand. Requires canCreateCollectibles permission.","operationId":"CollectibleBrandsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCollectibleBrandRequestDto"}}}},"responses":{"201":{"description":"Brand created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCollectibleBrandResponseDto"}}}},"400":{"description":"Invalid request data (e.g., slug already in use)"},"401":{"description":"Unauthorized."},"403":{"description":"User lacks permission to create collectibles"}},"security":[{"bearer":[]}],"summary":"Create a new collectible brand","tags":["CollectibleBrands"]},"get":{"description":"Retrieve collectible brands with optional filters: slug (exact match), name (exact match), searchString (searches slug, name, and description). Supports pagination.","operationId":"CollectibleBrandsController_retrieveAll","parameters":[{"name":"slug","required":false,"in":"query","description":"Filter by exact slug match","schema":{"example":"luxury-motors","type":"string"}},{"name":"name","required":false,"in":"query","description":"Filter by exact name match","schema":{"example":"Luxury Motors","type":"string"}},{"name":"searchString","required":false,"in":"query","description":"Universal search string that searches in slug, name, and description (partial match, case-insensitive)","schema":{"example":"luxury automotive","type":"string"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of brands to retrieve per page","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CollectibleBrandResponseDto"}}}}}}},"400":{"description":"Invalid query parameters."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get all collectible brands with filters","tags":["CollectibleBrands"]}},"/api/v1/collectibles/brands/{brandId}/confirm-logo":{"post":{"description":"Call this AFTER uploading the brand logo via the presigned URL. The logo object is re-fetched from R2 and run through the shared moderation gate; if rejected it is deleted and the request fails with 422. Only the brand creator may confirm.","operationId":"CollectibleBrandsController_confirmLogo","parameters":[{"name":"brandId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The uploaded logo passed moderation."},"401":{"description":"Unauthorized."},"403":{"description":"Caller is not the brand creator."},"404":{"description":"Brand not found."},"422":{"description":"The uploaded logo was rejected by moderation."}},"security":[{"bearer":[]}],"summary":"Confirm & moderate an uploaded brand logo","tags":["CollectibleBrands"]}},"/api/v1/collectibles/brands/me":{"get":{"description":"Retrieve all collectible brands created by the authenticated user. Supports same filters as the main GET endpoint.","operationId":"CollectibleBrandsController_retrieveMine","parameters":[{"name":"slug","required":false,"in":"query","description":"Filter by exact slug match","schema":{"example":"luxury-motors","type":"string"}},{"name":"name","required":false,"in":"query","description":"Filter by exact name match","schema":{"example":"Luxury Motors","type":"string"}},{"name":"searchString","required":false,"in":"query","description":"Universal search string that searches in slug, name, and description (partial match, case-insensitive)","schema":{"example":"luxury automotive","type":"string"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of brands to retrieve per page","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CollectibleBrandResponseDto"}}}}}}},"400":{"description":"Invalid query parameters."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get collectible brands created by the current user","tags":["CollectibleBrands"]}},"/api/v1/collectibles/brands/{brandId}":{"get":{"description":"Retrieve a specific collectible brand with creator info.","operationId":"CollectibleBrandsController_retrieveOne","parameters":[{"name":"brandId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CollectibleBrandResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"Brand not found."}},"security":[{"bearer":[]}],"summary":"Get a single collectible brand by ID","tags":["CollectibleBrands"]},"patch":{"description":"Update an existing collectible brand. Only the creator can update their brand. Can update name, slug, description, metadata, and associated collectibles. Requires canCreateCollectibles permission.","operationId":"CollectibleBrandsController_update","parameters":[{"name":"brandId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCollectibleBrandRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UpdateCollectibleBrandResponseDto"}}}}}},"400":{"description":"Invalid request data (e.g., slug already in use)"},"401":{"description":"Unauthorized."},"403":{"description":"User lacks permission to update collectibles or is not the creator"},"404":{"description":"Brand not found."}},"security":[{"bearer":[]}],"summary":"Update a collectible brand","tags":["CollectibleBrands"]},"delete":{"description":"Delete a collectible brand. Only the creator can delete their brand. Cannot delete a brand if collectibles are associated with it. Requires canCreateCollectibles permission.","operationId":"CollectibleBrandsController_delete","parameters":[{"name":"brandId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Brand deleted successfully"},"400":{"description":"Cannot delete brand - collectibles are associated with this brand"},"401":{"description":"Unauthorized."},"403":{"description":"User lacks permission to delete collectibles or is not the creator"},"404":{"description":"Brand not found."}},"security":[{"bearer":[]}],"summary":"Delete a collectible brand","tags":["CollectibleBrands"]}},"/api/v1/collectibles":{"post":{"description":"Creates a new collectible template without instances. Use the dedicated instances endpoint to add instances. Requires canCreateCollectibles permission.","operationId":"CollectiblesController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCollectibleRequestDto"}}}},"responses":{"201":{"description":"Collectible created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCollectibleResponseDto"}}}},"400":{"description":"Invalid request data (e.g., slug already in use)"},"401":{"description":"Unauthorized."},"403":{"description":"User lacks permission to create collectibles"}},"security":[{"bearer":[]}],"summary":"Create a new collectible","tags":["Collectibles"]},"get":{"description":"Retrieve collectibles with optional filters: id, slug, name search, searchString (searches name and description), type, onlyUniversal, and compatibleWith (package slug). Supports pagination. Does not include instances - use dedicated endpoint to fetch instances.","operationId":"CollectiblesController_retrieveAll","parameters":[{"name":"id","required":false,"in":"query","description":"Filter by collectible ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"slug","required":false,"in":"query","description":"Filter by exact slug match","schema":{"example":"ferrari-488","type":"string"}},{"name":"name","required":false,"in":"query","description":"Search by name (partial match, case-insensitive)","schema":{"example":"Ferrari","type":"string"}},{"name":"searchString","required":false,"in":"query","description":"Search string that searches in both name and description (partial match, case-insensitive)","schema":{"example":"luxury sports car","type":"string"}},{"name":"type","required":false,"in":"query","description":"Filter by collectible type","schema":{"example":"Vehicle","type":"string","enum":["Wearable","Placeable","Vehicle","Clothing","Accessory","Character","HomeItem","Property"]}},{"name":"onlyUniversal","required":false,"in":"query","description":"Filter to only universal collectibles (works across all packages)","schema":{"example":true,"type":"boolean"}},{"name":"compatibleWith","required":false,"in":"query","description":"Filter collectibles compatible with a specific package slug (includes universal collectibles)","schema":{"example":"my-game-package","type":"string"}},{"name":"brandId","required":false,"in":"query","description":"Filter by brand ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"brandSlug","required":false,"in":"query","description":"Filter by brand slug","schema":{"example":"luxury-motors","type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"Filter by creator ID (user who created the collectible)","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Field to sort by","schema":{"example":"createdAt","type":"string","enum":["name_asc","name_desc","createdAt","updatedAt","lastSaleAt","supply_asc","supply_desc","lastSalePrice","totalSalesCount","totalVolumeTraded","allTimeHighPrice","avgSalePrice"]}},{"name":"sortOrder","required":false,"in":"query","description":"Sort order direction (ASC or DESC)","schema":{"default":"DESC","example":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"minLastSalePrice","required":false,"in":"query","description":"Filter collectibles with last sale price greater than this value","schema":{"example":100,"type":"number"}},{"name":"maxLastSalePrice","required":false,"in":"query","description":"Filter collectibles with last sale price less than this value","schema":{"example":1000,"type":"number"}},{"name":"minAvgSalePrice","required":false,"in":"query","description":"Filter collectibles with average sale price greater than this value","schema":{"example":100,"type":"number"}},{"name":"maxAvgSalePrice","required":false,"in":"query","description":"Filter collectibles with average sale price less than this value","schema":{"example":1000,"type":"number"}},{"name":"minAllTimeHighPrice","required":false,"in":"query","description":"Filter collectibles with all-time high price greater than this value","schema":{"example":100,"type":"number"}},{"name":"maxAllTimeHighPrice","required":false,"in":"query","description":"Filter collectibles with all-time high price less than this value","schema":{"example":1000,"type":"number"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of collectibles to retrieve per page","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CollectibleResponseDto"}}}}}}},"400":{"description":"Invalid query parameters."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get all collectibles with filters","tags":["Collectibles"]}},"/api/v1/collectibles/{collectibleId}/instances":{"post":{"description":"Adds a new instance to a collectible template. Serial number will be auto-assigned sequentially. Requires canCreateCollectibles permission.","operationId":"CollectiblesController_addInstances","parameters":[{"name":"collectibleId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCollectibleInstancesRequestDto"}}}},"responses":{"201":{"description":"Instance added successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCollectibleInstanceResponseDto"}}}},"400":{"description":"Invalid request data (e.g., total instances would exceed supply)"},"401":{"description":"Unauthorized."},"403":{"description":"User lacks permission to create collectibles"},"404":{"description":"Collectible not found"}},"security":[{"bearer":[]}],"summary":"Add an instance to an existing collectible","tags":["Collectibles"]},"get":{"description":"Retrieve paginated instances for a specific collectible with optional filters: ownerId, serial, isTransferable, isLocked (marketplace status), locationType. Ordered by serial number.","operationId":"CollectiblesController_retrieveCollectibleInstances","parameters":[{"name":"collectibleId","required":true,"in":"path","schema":{"type":"string"}},{"name":"ownerId","required":false,"in":"query","description":"Filter by owner ID","schema":{"example":"user-uuid-123","type":"string"}},{"name":"serial","required":false,"in":"query","description":"Filter by serial number","schema":{"example":1,"type":"number"}},{"name":"isTransferable","required":false,"in":"query","description":"Filter by transferability","schema":{"example":true,"type":"boolean"}},{"name":"isLocked","required":false,"in":"query","description":"Filter by lock status (true = locked/listed, false = available)","schema":{"example":false,"type":"boolean"}},{"name":"locationType","required":false,"in":"query","description":"Filter by location type","schema":{"example":"user","type":"string"}},{"name":"page","required":true,"in":"query","description":"Page number for pagination","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CollectibleInstanceResponseDto"}}}}}}},"400":{"description":"Invalid query parameters."},"401":{"description":"Unauthorized."},"404":{"description":"Collectible not found."}},"security":[{"bearer":[]}],"summary":"Get instances for a collectible","tags":["Collectibles"]}},"/api/v1/collectibles/{collectibleId}/confirm-media":{"post":{"description":"Call this AFTER uploading the collectible thumbnail, 3D image and/or previews via the presigned URLs. Each uploaded object is re-fetched from R2 and run through the shared moderation gate; a rejected object is deleted and the request fails with 422. Only the creator may confirm.","operationId":"CollectiblesController_confirmMedia","parameters":[{"name":"collectibleId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmMediaRequestDto"}}}},"responses":{"200":{"description":"All uploaded media passed moderation."},"401":{"description":"Unauthorized."},"403":{"description":"Caller is not the collectible creator."},"404":{"description":"Collectible not found."},"422":{"description":"An uploaded object was rejected by moderation."}},"security":[{"bearer":[]}],"summary":"Confirm & moderate uploaded collectible media","tags":["Collectibles"]}},"/api/v1/collectibles/{collectibleId}/instances/{instanceId}/confirm-media":{"post":{"description":"Call this AFTER uploading an instance thumbnail, 3D image and/or previews via the presigned URLs. Each uploaded object is re-fetched from R2 and moderated; a rejected object is deleted and the request fails with 422. Only the instance owner may confirm.","operationId":"CollectiblesController_confirmInstanceMedia","parameters":[{"name":"collectibleId","required":true,"in":"path","schema":{"type":"string"}},{"name":"instanceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmMediaRequestDto"}}}},"responses":{"200":{"description":"All uploaded media passed moderation."},"401":{"description":"Unauthorized."},"403":{"description":"Caller does not own the instance."},"404":{"description":"Collectible instance not found."},"422":{"description":"An uploaded object was rejected by moderation."}},"security":[{"bearer":[]}],"summary":"Confirm & moderate uploaded collectible instance media","tags":["Collectibles"]}},"/api/v1/collectibles/me":{"get":{"description":"Retrieve all collectibles created by the authenticated user. Supports same filters as the main GET endpoint. Does not include instances - use dedicated endpoint to fetch instances.","operationId":"CollectiblesController_retrieveMine","parameters":[{"name":"id","required":false,"in":"query","description":"Filter by collectible ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"slug","required":false,"in":"query","description":"Filter by exact slug match","schema":{"example":"ferrari-488","type":"string"}},{"name":"name","required":false,"in":"query","description":"Search by name (partial match, case-insensitive)","schema":{"example":"Ferrari","type":"string"}},{"name":"searchString","required":false,"in":"query","description":"Search string that searches in both name and description (partial match, case-insensitive)","schema":{"example":"luxury sports car","type":"string"}},{"name":"type","required":false,"in":"query","description":"Filter by collectible type","schema":{"example":"Vehicle","type":"string","enum":["Wearable","Placeable","Vehicle","Clothing","Accessory","Character","HomeItem","Property"]}},{"name":"onlyUniversal","required":false,"in":"query","description":"Filter to only universal collectibles (works across all packages)","schema":{"example":true,"type":"boolean"}},{"name":"compatibleWith","required":false,"in":"query","description":"Filter collectibles compatible with a specific package slug (includes universal collectibles)","schema":{"example":"my-game-package","type":"string"}},{"name":"brandId","required":false,"in":"query","description":"Filter by brand ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"brandSlug","required":false,"in":"query","description":"Filter by brand slug","schema":{"example":"luxury-motors","type":"string"}},{"name":"creatorId","required":false,"in":"query","description":"Filter by creator ID (user who created the collectible)","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Field to sort by","schema":{"example":"createdAt","type":"string","enum":["name_asc","name_desc","createdAt","updatedAt","lastSaleAt","supply_asc","supply_desc","lastSalePrice","totalSalesCount","totalVolumeTraded","allTimeHighPrice","avgSalePrice"]}},{"name":"sortOrder","required":false,"in":"query","description":"Sort order direction (ASC or DESC)","schema":{"default":"DESC","example":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"minLastSalePrice","required":false,"in":"query","description":"Filter collectibles with last sale price greater than this value","schema":{"example":100,"type":"number"}},{"name":"maxLastSalePrice","required":false,"in":"query","description":"Filter collectibles with last sale price less than this value","schema":{"example":1000,"type":"number"}},{"name":"minAvgSalePrice","required":false,"in":"query","description":"Filter collectibles with average sale price greater than this value","schema":{"example":100,"type":"number"}},{"name":"maxAvgSalePrice","required":false,"in":"query","description":"Filter collectibles with average sale price less than this value","schema":{"example":1000,"type":"number"}},{"name":"minAllTimeHighPrice","required":false,"in":"query","description":"Filter collectibles with all-time high price greater than this value","schema":{"example":100,"type":"number"}},{"name":"maxAllTimeHighPrice","required":false,"in":"query","description":"Filter collectibles with all-time high price less than this value","schema":{"example":1000,"type":"number"}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of collectibles to retrieve per page","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CollectibleResponseDto"}}}}}}},"400":{"description":"Invalid query parameters."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get collectibles created by the current user","tags":["Collectibles"]}},"/api/v1/collectibles/{collectibleId}":{"get":{"description":"Retrieve a specific collectible with creator info and compatible packages. Does not include instances - use dedicated endpoint to fetch instances.","operationId":"CollectiblesController_retrieveOne","parameters":[{"name":"collectibleId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CollectibleResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"Collectible not found."}},"security":[{"bearer":[]}],"summary":"Get a single collectible by ID","tags":["Collectibles"]},"patch":{"description":"Update an existing collectible. Only the creator can update their collectible. Supply can only be increased, not decreased. Requires canCreateCollectibles permission.","operationId":"CollectiblesController_updateCollectible","parameters":[{"name":"collectibleId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCollectibleRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UpdateCollectibleResponseDto"}}}}}},"400":{"description":"Invalid request data (e.g., slug already in use, supply cannot be decreased)"},"401":{"description":"Unauthorized."},"403":{"description":"User lacks permission to update collectibles or is not the creator"},"404":{"description":"Collectible not found."}},"security":[{"bearer":[]}],"summary":"Update a collectible","tags":["Collectibles"]},"delete":{"description":"Delete an existing collectible and all its instances. Only the creator can delete their collectible. Cannot delete if there are instances owned by other users or if any instances are currently listed on the marketplace. Requires canCreateCollectibles permission.","operationId":"CollectiblesController_deleteCollectible","parameters":[{"name":"collectibleId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Collectible deleted successfully"},"400":{"description":"Collectible has instances owned by other users or instances currently listed on the marketplace."},"401":{"description":"Unauthorized."},"403":{"description":"User lacks permission to delete collectibles or is not the creator"},"404":{"description":"Collectible not found."}},"security":[{"bearer":[]}],"summary":"Delete a collectible","tags":["Collectibles"]}},"/api/v1/collectibles/instances/me":{"get":{"description":"Retrieve all collectible instances owned by the authenticated user with optional filters: serial, isTransferable, isLocked (marketplace status), locationType. Ordered by collectible name and serial number.","operationId":"CollectiblesController_retrieveMyInstances","parameters":[{"name":"serial","required":false,"in":"query","description":"Filter by serial number","schema":{"example":1,"type":"number"}},{"name":"isTransferable","required":false,"in":"query","description":"Filter by transferability","schema":{"example":true,"type":"boolean"}},{"name":"isLocked","required":false,"in":"query","description":"Filter by lock status (true = locked/listed, false = available)","schema":{"example":false,"type":"boolean"}},{"name":"locationType","required":false,"in":"query","description":"Filter by location type","schema":{"example":"user","type":"string"}},{"name":"page","required":true,"in":"query","description":"Page number for pagination","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":true,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CollectibleInstanceResponseDto"}}}}}}},"400":{"description":"Invalid query parameters."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get collectible instances owned by the current user","tags":["Collectibles"]}},"/api/v1/collectibles/instances/{instanceId}":{"get":{"description":"Retrieve a specific collectible instance with its collectible info, owner, and all instance data.","operationId":"CollectiblesController_retrieveOneInstance","parameters":[{"name":"instanceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/CollectibleInstanceResponseDto"}}}}}},"401":{"description":"Unauthorized."},"404":{"description":"Collectible instance not found."}},"security":[{"bearer":[]}],"summary":"Get a single collectible instance by ID","tags":["Collectibles"]},"patch":{"description":"Update an existing collectible instance. Only admin accounts can update instances. Can update traits, usage metrics, ownership, location, transferability, and previews. Cannot update locked instances (instances currently listed on the marketplace).","operationId":"CollectiblesController_updateCollectibleInstance","parameters":[{"name":"instanceId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCollectibleInstanceRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UpdateCollectibleInstanceResponseDto"}}}}}},"400":{"description":"Invalid request data or instance is locked (currently listed on marketplace)."},"401":{"description":"Unauthorized."},"403":{"description":"Admin access required."},"404":{"description":"Collectible instance not found."}},"security":[{"bearer":[]}],"summary":"Update a collectible instance (Admin only)","tags":["Collectibles"]},"delete":{"description":"Delete an existing collectible instance. Only the collectible creator can delete instances, and only if they also own that specific instance. Cannot delete locked instances (instances currently listed on the marketplace).","operationId":"CollectiblesController_deleteCollectibleInstance","parameters":[{"name":"instanceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Collectible instance deleted successfully"},"400":{"description":"Instance is locked (currently listed on marketplace)."},"401":{"description":"Unauthorized."},"403":{"description":"User is not the collectible creator or does not own this instance."},"404":{"description":"Collectible instance not found."}},"security":[{"bearer":[]}],"summary":"Delete a collectible instance","tags":["Collectibles"]}},"/api/v1/collectibles/listings":{"post":{"description":"List a collectible instance on the marketplace. The instance must be owned by the user (or collectible creator if not yet traded), be transferable, have no location (not in use), and not already listed. The instance will be locked while listed.","operationId":"ListingsController_createListing","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateListingRequestDto"}}}},"responses":{"201":{"description":"Listing created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectibleListingResponseDto"}}}},"400":{"description":"Invalid request data, instance not found, already listed, not transferable, or currently in use. A home listed below its area-derived floor returns `code: \"home_below_price_floor\"` with `minPriceLix`, `providedLix` and the offending `field` — render off the code, not the message."},"401":{"description":"Unauthorized."},"403":{"description":"User does not own the instance or instance cannot be listed"}},"security":[{"bearer":[]}],"summary":"Create a marketplace listing","tags":["Collectible Listings"]}},"/api/v1/collectibles/listings/my-listings":{"get":{"description":"Retrieve all listings created by the authenticated user with pagination and optional filters (status, listing type, collectible ID).","operationId":"ListingsController_getMyListings","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by listing status","schema":{"type":"string","enum":["ACTIVE","SOLD","CANCELLED"]}},{"name":"listingType","required":false,"in":"query","description":"Filter by listing type","schema":{"type":"string","enum":["FIXED_PRICE","OFFER_BASED"]}},{"name":"collectibleId","required":false,"in":"query","description":"Filter by collectible ID","schema":{"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","type":"string"}},{"name":"type","required":false,"in":"query","description":"Filter by collectible type","schema":{"type":"string","enum":["Wearable","Placeable","Vehicle","Clothing","Accessory","Character","HomeItem","Property"]}},{"name":"brandId","required":false,"in":"query","description":"Filter by brand ID","schema":{"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","type":"string"}},{"name":"brandSlug","required":false,"in":"query","description":"Filter by brand slug","schema":{"example":"acme-corp","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort listings by specific criteria","schema":{"example":"price_low_to_high","type":"string","enum":["price_low_to_high","price_high_to_low","newest","name_a_z","name_z_a"]}},{"name":"minPrice","required":false,"in":"query","description":"Minimum price filter (in LIX)","schema":{"minimum":0,"example":10,"type":"number"}},{"name":"maxPrice","required":false,"in":"query","description":"Maximum price filter (in LIX)","schema":{"minimum":0,"example":1000,"type":"number"}}],"responses":{"200":{"description":"Listings retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CollectibleListingResponseDto"}}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get my marketplace listings","tags":["Collectible Listings"]}},"/api/v1/collectibles/listings/all":{"get":{"description":"Retrieve all marketplace listings with pagination and optional filters (status, listing type, collectible ID, slug, seller ID). This is a public endpoint that can be accessed without authentication.","operationId":"ListingsController_getAllListings","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by listing status","schema":{"example":"ACTIVE","type":"string","enum":["ACTIVE","SOLD","CANCELLED"]}},{"name":"listingType","required":false,"in":"query","description":"Filter by listing type","schema":{"example":"FIXED_PRICE","type":"string","enum":["FIXED_PRICE","OFFER_BASED"]}},{"name":"collectibleInstanceId","required":false,"in":"query","description":"Filter by collectible instance ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"collectibleId","required":false,"in":"query","description":"Filter by collectible ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"slug","required":false,"in":"query","description":"Filter by collectible slug","schema":{"example":"rare-spaceship","type":"string"}},{"name":"sellerId","required":false,"in":"query","description":"Filter by seller user ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"type","required":false,"in":"query","description":"Filter by collectible type","schema":{"example":"Wearable","type":"string","enum":["Wearable","Placeable","Vehicle","Clothing","Accessory","Character","HomeItem","Property"]}},{"name":"brandId","required":false,"in":"query","description":"Filter by brand ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"brandSlug","required":false,"in":"query","description":"Filter by brand slug","schema":{"example":"acme-corp","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort listings by specific criteria","schema":{"example":"price_low_to_high","type":"string","enum":["price_low_to_high","price_high_to_low","newest","name_a_z","name_z_a"]}},{"name":"minPrice","required":false,"in":"query","description":"Minimum price filter (in LIX)","schema":{"minimum":0,"example":10,"type":"number"}},{"name":"maxPrice","required":false,"in":"query","description":"Maximum price filter (in LIX)","schema":{"minimum":0,"example":1000,"type":"number"}}],"responses":{"200":{"description":"Listings retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCollectibleListingResponseDto"}}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get all marketplace listings","tags":["Collectible Listings"]}},"/api/v1/collectibles/listings/{listingId}":{"get":{"description":"Retrieve detailed information about a specific marketplace listing including the collectible instance and collectible details.","operationId":"ListingsController_getListingById","parameters":[{"name":"listingId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Listing details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCollectibleListingResponseDto"}}}},"400":{"description":"Listing not found"},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get listing details","tags":["Collectible Listings"]}},"/api/v1/collectibles/listings/cancel":{"post":{"description":"Cancel an active marketplace listing. For FIXED_PRICE listings, this simply unlocks the instance and marks the listing as cancelled. For OFFER_BASED listings, all pending offers are automatically cancelled first (funds unlocked to buyers), then the listing is cancelled and the instance is unlocked. Only the seller can cancel their listing.","operationId":"ListingsController_cancelListing","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelListingRequestDto"}}}},"responses":{"200":{"description":"Listing cancelled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectibleListingResponseDto"}}}},"400":{"description":"Listing not found, not active, or failed to cancel pending offers"},"401":{"description":"Unauthorized."},"403":{"description":"Only the seller can cancel the listing"}},"security":[{"bearer":[]}],"summary":"Cancel a listing (seller only)","tags":["Collectible Listings"]}},"/api/v1/collectibles/trades/instance":{"get":{"description":"Retrieve complete trade history for a specific collectible instance with pagination and filtering options. Supports filtering by trade type, time period (start/end dates), buyer, and seller. Useful for analyzing price trends, ownership history, and market activity.","operationId":"TradesController_getInstanceTrades","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"instanceId","required":true,"in":"query","description":"The UUID of the collectible instance","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"tradeType","required":false,"in":"query","description":"Filter by trade type","schema":{"example":"INSTANT_BUY","type":"string","enum":["INSTANT_BUY","OFFER_ACCEPTED"]}},{"name":"startDate","required":false,"in":"query","description":"Filter trades from this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter trades until this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"buyerId","required":false,"in":"query","description":"Filter by buyer user ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"sellerId","required":false,"in":"query","description":"Filter by seller user ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"minPrice","required":false,"in":"query","description":"Filter by minimum trade price (LIX)","schema":{"example":50,"type":"number"}},{"name":"maxPrice","required":false,"in":"query","description":"Filter by maximum trade price (LIX)","schema":{"example":500,"type":"number"}}],"responses":{"200":{"description":"Trade history retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCollectibleTradeResponseDto"}}}}},"400":{"description":"Instance not found or invalid query parameters"}},"summary":"Get historical trades for a collectible instance","tags":["Collectible Trades"]}},"/api/v1/collectibles/trades/collectible":{"get":{"description":"Retrieve complete trade history for all instances of a specific collectible with pagination and filtering options. Supports filtering by trade type, time period (start/end dates), buyer, and seller. Useful for analyzing overall collectible market trends, total trading volume, and price history across all instances.","operationId":"TradesController_getCollectibleTrades","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"collectibleId","required":true,"in":"query","description":"The UUID of the collectible","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"tradeType","required":false,"in":"query","description":"Filter by trade type","schema":{"example":"INSTANT_BUY","type":"string","enum":["INSTANT_BUY","OFFER_ACCEPTED"]}},{"name":"startDate","required":false,"in":"query","description":"Filter trades from this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter trades until this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"buyerId","required":false,"in":"query","description":"Filter by buyer user ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"sellerId","required":false,"in":"query","description":"Filter by seller user ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"minPrice","required":false,"in":"query","description":"Filter by minimum trade price (LIX)","schema":{"example":50,"type":"number"}},{"name":"maxPrice","required":false,"in":"query","description":"Filter by maximum trade price (LIX)","schema":{"example":500,"type":"number"}}],"responses":{"200":{"description":"Trade history retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCollectibleTradeResponseDto"}}}}},"400":{"description":"Collectible not found or invalid query parameters"}},"summary":"Get historical trades for all instances of a collectible","tags":["Collectible Trades"]}},"/api/v1/collectibles/trades/user":{"get":{"description":"Retrieve complete trade history for a specific user with pagination and filtering options. Returns trades where the user was either buyer or seller. Supports filtering by showOnlySales, showOnlyBuys, trade type, price range (min/max), and time period (start/end dates). Useful for analyzing user trading activity, purchase history, and sales records.","operationId":"TradesController_getUserTrades","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"userId","required":true,"in":"query","description":"The UUID of the user","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"showOnlySales","required":false,"in":"query","description":"Show only sales (user as seller)","schema":{"example":true,"type":"boolean"}},{"name":"showOnlyBuys","required":false,"in":"query","description":"Show only buys (user as buyer)","schema":{"example":true,"type":"boolean"}},{"name":"tradeType","required":false,"in":"query","description":"Filter by trade type","schema":{"example":"INSTANT_BUY","type":"string","enum":["INSTANT_BUY","OFFER_ACCEPTED"]}},{"name":"startDate","required":false,"in":"query","description":"Filter trades from this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter trades until this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"minPrice","required":false,"in":"query","description":"Filter by minimum trade price (LIX)","schema":{"example":50,"type":"number"}},{"name":"maxPrice","required":false,"in":"query","description":"Filter by maximum trade price (LIX)","schema":{"example":500,"type":"number"}}],"responses":{"200":{"description":"Trade history retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCollectibleTradeResponseDto"}}}}},"400":{"description":"User not found or invalid query parameters"}},"summary":"Get historical trades for a user","tags":["Collectible Trades"]}},"/api/v1/redeemable-codes":{"post":{"description":"Admin access is required to access this route.","operationId":"RedeemableController_createRedeemableCode","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRedeemableCodeRequestDto"}}}},"responses":{"201":{"description":"Redeemable code created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemableCodeResponseDto"}}}},"400":{"description":"Invalid input data."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Create a new redeemable code (Admin only)","tags":["Redeemable Codes"]}},"/api/v1/redeemable-codes/all":{"get":{"description":"Admin access is required to access this route.","operationId":"RedeemableController_getAllRedeemableCodes","parameters":[{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page (max 50)","schema":{"maximum":50,"default":20,"example":20,"type":"number"}},{"name":"userId","required":false,"in":"query","description":"Filter by user ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"redeemed","required":false,"in":"query","description":"Filter by redeemed status (true = redeemed, false = not redeemed)","schema":{"example":true,"type":"boolean"}},{"name":"createdBefore","required":false,"in":"query","description":"Filter codes created before this date (ISO 8601 format)","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"createdAfter","required":false,"in":"query","description":"Filter codes created after this date (ISO 8601 format)","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}}],"responses":{"200":{"description":"Paginated redeemable codes retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemableCodeCollectionResponseDto"}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get all redeemable codes with optional filters and pagination (Admin only)","tags":["Redeemable Codes"]}},"/api/v1/redeemable-codes/{id}":{"get":{"description":"Admin access is required to access this route.","operationId":"RedeemableController_getRedeemableCode","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Redeemable code retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemableCodeResponseDto"}}}},"401":{"description":"Unauthorized."},"404":{"description":"Redeemable code not found."}},"security":[{"bearer":[]}],"summary":"Get a redeemable code by ID (Admin only)","tags":["Redeemable Codes"]}},"/api/v1/redeemable-codes/user/{userId}":{"get":{"description":"Admin access is required to access this route.","operationId":"RedeemableController_getUserRedeemableCodes","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page (max 50)","schema":{"maximum":50,"default":20,"example":20,"type":"number"}}],"responses":{"200":{"description":"Paginated redeemable codes retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemableCodeCollectionResponseDto"}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get all redeemable codes for a user with pagination (Admin only)","tags":["Redeemable Codes"]}},"/api/v1/redeemable-codes/redeem":{"post":{"operationId":"RedeemableController_redeemCode","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemCodeRequestDto"}}}},"responses":{"200":{"description":"Code redeemed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeemCodeResponseDto"}}}},"400":{"description":"Invalid code, code already redeemed, code expired, or code does not belong to user."},"401":{"description":"Unauthorized."},"404":{"description":"Redeemable code not found."}},"security":[{"bearer":[]}],"summary":"Redeem a code for the authenticated user","tags":["Redeemable Codes"]}},"/api/v1/pages/admin":{"post":{"description":"Admin-only endpoint to create a new page. The version number is automatically set to 1. The authenticated admin user is recorded as the creator.","operationId":"PagesController_createPage","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePageDto"}}}},"responses":{"201":{"description":"Page created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageResponseDto"}}}},"400":{"description":"Invalid request data or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A page with this slug already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Create a new page","tags":["Pages"]},"get":{"description":"Admin-only endpoint to retrieve a paginated list of all pages. Supports sorting by creation date, update date, title, slug, or version number.","operationId":"PagesController_getPages","parameters":[{"name":"searchString","required":false,"in":"query","description":"Search string to filter pages by slug, title, or content","schema":{"example":"about","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"default":10,"example":10,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Sort by field","schema":{"default":"createdAt","example":"createdAt","type":"string","enum":["createdAt","updatedAt","title","slug","versionNumber"]}},{"name":"sortOrder","required":false,"in":"query","description":"Sort order","schema":{"default":"DESC","example":"DESC","type":"string","enum":["ASC","DESC"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PageResponseDto"}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get paginated list of pages","tags":["Pages"]}},"/api/v1/pages/admin/{id}":{"patch":{"description":"Admin-only endpoint to update an existing page. Can update title, slug, and/or content. The version number is automatically incremented and the updatedBy field is set to the authenticated admin user.","operationId":"PagesController_updatePage","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePageDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PageResponseDto"}}}}}},"400":{"description":"Invalid request data or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Page not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A page with this slug already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update an existing page","tags":["Pages"]},"delete":{"description":"Admin-only endpoint to delete an existing page by its ID. This action is permanent and cannot be undone.","operationId":"PagesController_deletePage","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/Object"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Page not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Delete a page","tags":["Pages"]}},"/api/v1/pages/{slug}":{"get":{"description":"Public endpoint to retrieve a specific page by its slug. Returns the full page content including metadata.","operationId":"PagesController_getPageBySlug","parameters":[{"name":"slug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PageResponseDto"}}}}}},"404":{"description":"Page not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"Get a page by slug","tags":["Pages"]}},"/api/v1/mass-email/closed-alpha":{"post":{"description":"Admin-only endpoint to send closed alpha invites to an array of emails. For each email, generates a unique invite code and sends it via email. Processes emails in the background with rate limiting (1 email every 10 seconds) to prevent service overload.","operationId":"MassEmailController_sendClosedAlphaInvites","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendClosedAlphaInvitesRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/SendClosedAlphaInvitesResponseDto"}}}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Send closed alpha invites","tags":["Mass Email"]}},"/api/v1/mass-email/closed-alpha-internal":{"post":{"description":"Internal endpoint to send closed alpha invites to an array of emails.","operationId":"MassEmailController_sendClosedAlphaInvitesInternal","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendClosedAlphaInvitesRequestDto"}}}},"responses":{"204":{"description":"Request received."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]},{"shared_secret":[]}],"summary":"Send closed alpha invites to an array of emails","tags":["Mass Email"]}},"/api/v1/mass-email/logs":{"get":{"description":"Admin-only endpoint to retrieve a paginated list of mass email logs. Supports filtering by campaign name and recipient email. Returns logs ordered by most recent first.","operationId":"MassEmailController_getMassEmailLogs","parameters":[{"name":"page","required":false,"in":"query","description":"The page number to retrieve.","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of items to retrieve per page.","schema":{"maximum":50,"default":20,"type":"number"}},{"name":"campaignName","required":false,"in":"query","description":"Filter by campaign name","schema":{"example":"closed-alpha","type":"string"}},{"name":"recipientEmail","required":false,"in":"query","description":"Filter by recipient email","schema":{"example":"user@example.com","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MassEmailLogResponseDto"}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get mass email logs","tags":["Mass Email"]}},"/api/v1/server-plans":{"get":{"description":"Retrieve available server plans with filtering, sorting, and pagination options. Returns active plans by default.","operationId":"ServerPlansController_getPlans","parameters":[{"name":"name","required":false,"in":"query","description":"Filter by plan name (partial match, case-insensitive)","schema":{"example":"Basic","type":"string"}},{"name":"isActive","required":false,"in":"query","description":"Filter by active status","schema":{"example":true,"type":"boolean"}},{"name":"region","required":false,"in":"query","description":"Filter by region availability","schema":{"example":"us-east","type":"string"}},{"name":"monthlyAvailable","required":false,"in":"query","description":"Filter by monthly availability","schema":{"example":true,"type":"boolean"}},{"name":"minCpuCores","required":false,"in":"query","description":"Minimum CPU cores","schema":{"example":2,"type":"number"}},{"name":"maxCpuCores","required":false,"in":"query","description":"Maximum CPU cores","schema":{"example":8,"type":"number"}},{"name":"minRamMb","required":false,"in":"query","description":"Minimum RAM in MB","schema":{"example":2048,"type":"number"}},{"name":"maxRamMb","required":false,"in":"query","description":"Maximum RAM in MB","schema":{"example":16384,"type":"number"}},{"name":"minLixPrice","required":false,"in":"query","description":"Minimum LIX price","schema":{"example":50,"type":"number"}},{"name":"maxLixPrice","required":false,"in":"query","description":"Maximum LIX price","schema":{"example":500,"type":"number"}},{"name":"orderBy","required":false,"in":"query","description":"The field to order results by","schema":{"default":"lixPrice","type":"string","enum":["name","lixPrice","cpuCores","ramMb","storageMb","createdAt","updatedAt"]}},{"name":"orderDir","required":false,"in":"query","description":"The direction to order results in","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"page","required":false,"in":"query","description":"The page number to retrieve","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"The number of plans to retrieve per page","schema":{"maximum":50,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServerPlanResponseDto"}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Get available server plans","tags":["Server Plans"]}},"/api/v1/server-plans/admin":{"post":{"description":"Admin-only endpoint to create a new server plan for provisioned servers.","operationId":"ServerPlansController_createPlan","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateServerPlanDto"}}}},"responses":{"201":{"description":"Server plan created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerPlanResponseDto"}}}},"400":{"description":"Invalid request data or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Server plan with this slug already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Create a new server plan","tags":["Server Plans"]}},"/api/v1/server-plans/admin/{id}":{"patch":{"description":"Admin-only endpoint to update an existing server plan. Only provided fields will be updated.","operationId":"ServerPlansController_updatePlan","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateServerPlanDto"}}}},"responses":{"200":{"description":"Server plan updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerPlanResponseDto"}}}},"400":{"description":"Invalid request data or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Server plan not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Server plan with this slug already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update an existing server plan","tags":["Server Plans"]},"delete":{"description":"Admin-only endpoint to soft delete a server plan. The slug is automatically modified to free it up for future use. The plan will be marked as deleted but historical data is preserved.","operationId":"ServerPlansController_deletePlan","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Server plan deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerPlanResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Server plan not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Delete a server plan","tags":["Server Plans"]}},"/api/v1/server-plans/admin/vultr-regions":{"get":{"description":"Admin-only endpoint to fetch available regions from the Vultr API for server provisioning.","operationId":"ServerPlansController_getVultrRegions","parameters":[],"responses":{"200":{"description":"List of available Vultr regions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/VultrRegionResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get available Vultr regions","tags":["Server Plans"]}},"/api/v1/server-plans/admin/vultr-regions/{regionId}/availability":{"get":{"description":"Admin-only endpoint to fetch available compute plans for a specific region from the Vultr API.","operationId":"ServerPlansController_getVultrRegionAvailability","parameters":[{"name":"regionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"List of available compute plan IDs in the region","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VultrAvailabilityResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get available compute plans in a Vultr region","tags":["Server Plans"]}},"/api/v1/discord/connect":{"get":{"description":"Redirects user to Discord OAuth authorization page","operationId":"DiscordController_connect","parameters":[{"name":"client","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns Discord OAuth URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectResponseDto"}}}},"401":{"description":"User not authenticated"},"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Initiate Discord OAuth connection","tags":["Discord","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported at this time."}}},"/api/v1/discord/callback":{"get":{"description":"Handles the OAuth callback from Discord and redirects to frontend","operationId":"DiscordController_callback","parameters":[{"name":"code","required":true,"in":"query","schema":{"type":"string"}},{"name":"state","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"400":{"description":"Invalid authorization code or state"}},"summary":"Discord OAuth callback","tags":["Discord"]}},"/api/v1/discord/disconnect":{"delete":{"description":"Unlink Discord account from the current user","operationId":"DiscordController_disconnect","parameters":[],"responses":{"200":{"description":"Discord account successfully disconnected"},"401":{"description":"User not authenticated"},"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Disconnect Discord account","tags":["Discord","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported at this time."}}},"/api/v1/discord/status":{"get":{"description":"Check if user has Discord account linked","operationId":"DiscordController_getStatus","parameters":[],"responses":{"200":{"description":"Returns Discord connection status"},"401":{"description":"User not authenticated"}},"security":[{"bearer":[]}],"summary":"Get Discord connection status","tags":["Discord"]}},"/api/v1/data-store":{"get":{"description":"List keys in this world, optionally filtered by key prefix, with cursor pagination. Returns keys and their metadata only — read a value with GET /:key.","operationId":"DataStoreController_list","parameters":[{"name":"x-helix-world-id","in":"header","description":"Target world id. REQUIRED when authenticating with a platform (client/access) token; ignored for world-session tokens (which carry the world id in the token).","required":false,"schema":{"type":"string"}},{"name":"prefix","required":false,"in":"query","description":"Only return keys that begin with this prefix (e.g. \"player:\"). Useful for per-player or per-namespace scans.","schema":{"example":"player:","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Keys per page. Defaults to the maximum.","schema":{"maximum":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Cursor for pagination: pass the previous response nextCursor to continue.","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List keys","tags":["Data Store"]}},"/api/v1/data-store/{key}":{"get":{"description":"Read a durable value by key from this world.","operationId":"DataStoreController_get","parameters":[{"name":"x-helix-world-id","in":"header","description":"Target world id. REQUIRED when authenticating with a platform (client/access) token; ignored for world-session tokens (which carry the world id in the token).","required":false,"schema":{"type":"string"}},{"name":"key","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The stored value, its version, and timestamps."}},"security":[{"bearer":[]}],"summary":"Get a value","tags":["Data Store"]},"put":{"description":"Create or overwrite a durable value. Pass expectedVersion for optimistic concurrency. Subject to the per-world free-tier quotas and write rate limit.","operationId":"DataStoreController_set","parameters":[{"name":"x-helix-world-id","in":"header","description":"Target world id. REQUIRED when authenticating with a platform (client/access) token; ignored for world-session tokens (which carry the world id in the token).","required":false,"schema":{"type":"string"}},{"name":"key","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetDataStoreEntryDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Set a value","tags":["Data Store"]},"delete":{"description":"Remove a durable value by key from this world. Pass expectedVersion for optimistic concurrency. Counts against the write rate limit.","operationId":"DataStoreController_delete","parameters":[{"name":"x-helix-world-id","in":"header","description":"Target world id. REQUIRED when authenticating with a platform (client/access) token; ignored for world-session tokens (which carry the world id in the token).","required":false,"schema":{"type":"string"}},{"name":"key","required":true,"in":"path","schema":{"type":"string"}},{"name":"expectedVersion","required":false,"in":"query","description":"Optional optimistic-concurrency version. Pass the version you last read to refuse the delete if the value has changed since.","schema":{"example":3,"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Delete a value","tags":["Data Store"]}},"/api/v1/data-store/{key}/increment":{"post":{"description":"Atomically add whole-number deltas to a counter key (community totals, votes, boss HP) and return the post-increment values. Counters are server state: the game server or creator tooling writes them, never a player session.","operationId":"DataStoreController_increment","parameters":[{"name":"x-helix-world-id","in":"header","description":"Target world id. REQUIRED when authenticating with a platform (client/access) token; ignored for world-session tokens (which carry the world id in the token).","required":false,"schema":{"type":"string"}},{"name":"key","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncrementDataStoreEntryDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Increment counter fields","tags":["Data Store"]}},"/api/v1/leaderboard/{board}/score":{"post":{"description":"Submit a score for one player on one board, keeping the best of it and whatever is already stored. A submit that loses to a better stored score — or that falls short of a full board's cutoff — is a normal 200 with updated:false, not an error, so a client may safely retry. `best` is the score the player is standing on, or null when they are off the board.","operationId":"LeaderboardController_submit","parameters":[{"name":"x-helix-world-id","in":"header","description":"Target world id. REQUIRED when authenticating with a platform (client/access) token; ignored for world-session tokens (which carry the world id in the token).","required":false,"schema":{"type":"string"}},{"name":"board","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitScoreDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Submit a score","tags":["Data Store"]}},"/api/v1/leaderboard/{board}":{"get":{"description":"Read one board top-first. Open to any authenticated caller in the world, like every other Data Store read.","operationId":"LeaderboardController_top","parameters":[{"name":"x-helix-world-id","in":"header","description":"Target world id. REQUIRED when authenticating with a platform (client/access) token; ignored for world-session tokens (which carry the world id in the token).","required":false,"schema":{"type":"string"}},{"name":"board","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"How many ranked entries to return (1-100). Defaults to 25.","schema":{"example":25,"type":"number"}},{"name":"order","required":false,"in":"query","description":"Which end of the board ranks first: \"desc\" highest-score-first (default), \"asc\" lowest-first.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"The ranked entries, and whether the board stores more than this page returned."}},"security":[{"bearer":[]}],"summary":"Read a board","tags":["Data Store"]}},"/api/v1/waitlist/entries":{"post":{"description":"Public endpoint to submit a waitlist email. Requests are deduplicated by normalized email and rate-limited by hashed network fingerprints.","operationId":"WaitlistController_createEntry","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWaitlistEntryDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/WaitlistEntryResponseDto"}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"429":{"description":"Too many attempts from the same client","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"summary":"Join waitlist","tags":["Waitlist"]}},"/api/v1/launcher/products":{"get":{"description":"Returns every non-deleted launcher product ordered alphabetically by name. Phase 3 alpha policy: any authenticated user sees all products. Entitlement gating will be added in a future milestone.","operationId":"LauncherProductsController_listAll","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LauncherProductResponseDto"}}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List all launcher products.","tags":["Launcher / Products"]}},"/api/v1/launcher/products/{slug}":{"get":{"description":"Returns the product matching the given slug. Used by the launcher CLI and the launcher app to translate slugs into the UUIDs that admin endpoints require.","operationId":"LauncherProductsController_getBySlug","parameters":[{"name":"slug","required":true,"in":"path","description":"Human-readable launcher product slug (e.g. `main-game`).","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/LauncherProductResponseDto"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Launcher product not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Resolve a launcher product by its human-readable slug.","tags":["Launcher / Products"]}},"/api/v1/launcher/products/{productSlug}/branches":{"get":{"description":"Returns the product's branches with the build each one currently points to (null when no build has been promoted yet). Used by the launcher CLI and app to translate branch names into the UUIDs that admin endpoints require.","operationId":"LauncherBranchesController_listByProductSlug","parameters":[{"name":"productSlug","required":true,"in":"path","description":"Human-readable launcher product slug (e.g. `main-game`).","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LauncherBranchResponseDto"}}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Launcher product not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List all branches for a launcher product (by slug).","tags":["Launcher / Branches"]}},"/api/v1/launcher/manifest/{productSlug}/{branchName}":{"get":{"description":"Returns the parsed manifest JSON, the manifest hash, build version, and patch notes. Does NOT include presigned chunk URLs — use POST chunk-urls to request those separately, supplying only the hashes you need to download.","operationId":"LauncherManifestsController_getCurrentManifest","parameters":[{"name":"productSlug","required":true,"in":"path","schema":{"type":"string"}},{"name":"branchName","required":true,"in":"path","schema":{"type":"string"}},{"name":"platform","required":true,"in":"query","description":"Target platform for the manifest (e.g. win64, macos).","schema":{"maxLength":32,"example":"win64","type":"string"}},{"name":"manifestHash","required":false,"in":"query","description":"Optional 64-char hex SHA-256 of the manifest the caller already holds. When provided, the endpoint verifies the branch still points at that build. If the branch has advanced to a different build, a 404 is returned with the current manifest hash in the error message.","schema":{"minLength":64,"maxLength":64,"example":"a1b2c3d4e5f6071829304a5b6c7d8e9fa0b1c2d3e4f50617283940a1b2c3d4e5","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/ManifestResponseDto"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Product, branch, or build not found, or no build is currently published on the requested platform.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Fetch the current manifest body for a (product, branch, platform).","tags":["Launcher / Manifests"]}},"/api/v1/launcher/manifest/{productSlug}/{branchName}/chunk-urls":{"post":{"description":"Given a manifest hash and a list of chunk hashes, returns a presigned GET URL for each chunk that is present in the manifest. Chunk hashes not in the manifest are silently omitted. Returns 409 if the supplied manifestHash no longer matches the current build — the client should re-fetch the manifest body and retry.","operationId":"LauncherManifestsController_getChunkUrls","parameters":[{"name":"productSlug","required":true,"in":"path","schema":{"type":"string"}},{"name":"branchName","required":true,"in":"path","schema":{"type":"string"}},{"name":"platform","required":true,"in":"query","description":"Target platform (e.g. \"win64\"). Must match the build the manifest was published for.","schema":{"maxLength":32,"example":"win64","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetChunkUrlsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/ChunkUrlsResponseDto"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Product, branch, or build not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"Request presigned R2 download URLs for a subset of chunks.","tags":["Launcher / Manifests"]}},"/api/v1/admin/launcher/branches":{"get":{"description":"Returns all launcher branches ordered by creation date (oldest first). Optionally filter to a single product via productSlug, and include archived branches via ?includeArchived=true.","operationId":"LauncherBranchesAdminController_listAll","parameters":[{"name":"productSlug","required":false,"in":"query","description":"Filter to branches of a specific product.","schema":{"type":"string"}},{"name":"includeArchived","required":false,"in":"query","description":"Include archived (soft-deleted) branches. Default: false.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LauncherBranchAdminResponseDto"}}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Product not found (when productSlug is supplied).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] List launcher branches.","tags":["Launcher Admin / Branches"]},"post":{"description":"Creates a new branch on a non-archived product and writes the matching branch pointer row (required by the promote endpoint). Branch name is immutable after creation.","operationId":"LauncherBranchesAdminController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLauncherBranchDto"}}}},"responses":{"201":{"description":"Branch created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LauncherBranchAdminResponseDto"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Product not found or is archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A branch with this name already exists on the product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Create a launcher branch.","tags":["Launcher Admin / Branches"]}},"/api/v1/admin/launcher/branches/{branchId}":{"get":{"description":"Returns the branch matching the given UUID, including archived branches.","operationId":"LauncherBranchesAdminController_getById","parameters":[{"name":"branchId","required":true,"in":"path","description":"Branch UUID.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/LauncherBranchAdminResponseDto"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Branch not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get a launcher branch by ID.","tags":["Launcher Admin / Branches"]},"patch":{"description":"Updates the description of a non-archived branch. Branch name and productId are immutable — rename by creating a new branch and archiving the old one.","operationId":"LauncherBranchesAdminController_update","parameters":[{"name":"branchId","required":true,"in":"path","description":"Branch UUID.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLauncherBranchDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/LauncherBranchAdminResponseDto"}}}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Branch not found or is archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update a launcher branch.","tags":["Launcher Admin / Branches"]}},"/api/v1/admin/launcher/branches/{branchId}/archive":{"post":{"description":"Soft-deletes the branch. The branch pointer row is preserved as audit data. Archiving the last active branch on a product is allowed.","operationId":"LauncherBranchesAdminController_archive","parameters":[{"name":"branchId","required":true,"in":"path","description":"Branch UUID.","schema":{"type":"string"}}],"responses":{"200":{"description":"Branch archived.","content":{"application/json":{"schema":{"properties":{"archivedAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Branch not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Branch is already archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Archive a launcher branch.","tags":["Launcher Admin / Branches"]}},"/api/v1/admin/launcher/branches/{branchId}/unarchive":{"post":{"description":"Restores a soft-deleted branch. Blocked if the parent product is archived — unarchive the product first (which cascade-restores all its branches).","operationId":"LauncherBranchesAdminController_unarchive","parameters":[{"name":"branchId","required":true,"in":"path","description":"Branch UUID.","schema":{"type":"string"}}],"responses":{"200":{"description":"Branch restored.","content":{"application/json":{"schema":{"properties":{"restoredAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Branch not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Branch is not archived, or parent product is archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Unarchive a launcher branch.","tags":["Launcher Admin / Branches"]}},"/api/v1/admin/launcher/branches/{branchId}/set-default":{"post":{"description":"Atomically sets is_default=TRUE on this branch and FALSE on all other branches of the same product. Idempotent — calling on an already-default branch returns success without changes.","operationId":"LauncherBranchesAdminController_setDefault","parameters":[{"name":"branchId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/LauncherBranchAdminResponseDto"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Branch not found or archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Set this branch as the default for its product.","tags":["Launcher Admin / Branches"]}},"/api/v1/admin/launcher/branches/{branchId}/promote":{"post":{"description":"Updates the branch pointer to the supplied build and writes a row to launcher_build_promotions. Runs inside a single transaction with a row-level lock on the pointer, so concurrent promotions on the same branch serialize and never lose audit rows. Re-promoting the current build still records a promotion — this is intentional, the table is an audit log.","operationId":"LauncherBranchesAdminController_promote","parameters":[{"name":"branchId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromoteBranchDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/PromoteBranchResponseDto"}}}}}},"400":{"description":"Build belongs to a different product than the branch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Branch or build not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Promote a build to a branch.","tags":["Launcher Admin / Branches"]}},"/api/v1/admin/launcher/builds":{"get":{"description":"Returns builds ordered by creation date (newest first). Filter by productSlug, status, or platform.","operationId":"LauncherBuildsAdminController_listAll","parameters":[{"name":"productSlug","required":false,"in":"query","description":"Filter to builds of a specific product.","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by build status.","schema":{"enum":["pending","finalized"],"type":"string"}},{"name":"platform","required":false,"in":"query","description":"Filter by platform (e.g. \"win64\").","schema":{"type":"string"}},{"name":"buildId","required":false,"in":"query","description":"Search by the human-readable build version string (build_id column, not the UUID primary key). Case-insensitive substring match.","schema":{"type":"string"}},{"name":"branchId","required":false,"in":"query","description":"Filter to builds currently promoted to this branch (branch UUID).","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LauncherBuildAdminResponseDto"}}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Product not found (when productSlug is supplied).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] List launcher builds.","tags":["Launcher Admin / Builds"]}},"/api/v1/admin/launcher/builds/{buildId}":{"get":{"description":"Returns the build matching the given UUID.","operationId":"LauncherBuildsAdminController_getById","parameters":[{"name":"buildId","required":true,"in":"path","description":"Build UUID (primary key).","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/LauncherBuildAdminResponseDto"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Build not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get a launcher build by ID.","tags":["Launcher Admin / Builds"]},"patch":{"description":"Sets or clears the patchNotes markdown field on a build. All other build fields (buildId, platform, status, manifestUrl, manifestHash) are immutable post-creation and cannot be modified via this endpoint.","operationId":"LauncherBuildsAdminController_updatePatchNotes","parameters":[{"name":"buildId","required":true,"in":"path","description":"Build UUID (primary key).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLauncherBuildDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/LauncherBuildAdminResponseDto"}}}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Build not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update patch notes for a build.","tags":["Launcher Admin / Builds"]}},"/api/v1/admin/launcher/builds/open":{"post":{"description":"Creates a pending launcher_builds row and returns its UUID plus a presigned PUT URL for the manifest. Use the returned launcherBuildId as :buildId for register-chunks and finalize. If a pending build with the same (productId, buildId, platform) already exists it is replaced; a finalized build with the same composite key is rejected with 409.","operationId":"LauncherBuildsAdminController_openBuild","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenBuildDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/OpenBuildResponseDto"}}}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Launcher product not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A finalized build with this composite key already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Open a new build (phase 1 of 3)","tags":["Launcher Admin / Builds"]}},"/api/v1/admin/launcher/builds/{buildId}/register-chunks":{"post":{"description":"Accepts up to 1 000 chunk hashes per call. For each hash: returns alreadyExists=true if the chunk is already in R2, otherwise issues a fresh 1-hour presigned PUT URL. Re-posting the same hashes returns fresh URLs, so re-calling this endpoint also serves as URL refresh — no separate refresh-upload-urls endpoint is needed.","operationId":"LauncherBuildsAdminController_registerChunks","parameters":[{"name":"buildId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterChunksDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/RegisterChunksResponseDto"}}}}}},"400":{"description":"Invalid chunk hash format, batch too large, or build is already finalized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Build not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Register a batch of chunks for a pending build (phase 2 of 3)","tags":["Launcher Admin / Builds"]}},"/api/v1/admin/launcher/builds/{buildId}/finalize":{"post":{"description":"Verifies the manifest is present in R2 and matches the supplied SHA-256, then transitions the build from pending to finalized. Returns 409 if the build is already finalized.","operationId":"LauncherBuildsAdminController_finalize","parameters":[{"name":"buildId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalizeBuildDto"}}}},"responses":{"201":{"description":"Build finalized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LauncherBuildResponseDto"}}}},"400":{"description":"Manifest missing in R2 or manifest hash mismatch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Build not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Build is already finalized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Finalize a build (phase 3 of 3)","tags":["Launcher Admin / Builds"]}},"/api/v1/admin/launcher/installer-releases/upload-url":{"post":{"description":"Issues a 1-hour presigned R2 PUT URL for uploading a launcher installer artifact (.exe, .exe.blockmap, or .yml update manifest). The artifact must be uploaded via HTTP PUT to the returned upload_url with the Content-Type header matching the requested content_type. The public_url is where the artifact will be accessible after upload.","operationId":"LauncherInstallerReleasesAdminController_getUploadUrl","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallerUploadUrlRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/InstallerUploadUrlResponseDto"}}}}}},"400":{"description":"Invalid filename or content_type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get a presigned PUT URL for uploading a launcher installer artifact","tags":["Launcher Admin / Installer Releases"]}},"/api/v1/admin/launcher/products":{"get":{"description":"Returns all launcher products ordered alphabetically by name. Pass ?includeArchived=true to include soft-deleted products.","operationId":"LauncherProductsAdminController_listAll","parameters":[{"name":"includeArchived","required":false,"in":"query","description":"Include archived (soft-deleted) products. Default: false.","schema":{"type":"boolean"}},{"name":"search","required":false,"in":"query","description":"Partial case-insensitive match on product slug or name.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LauncherProductAdminResponseDto"}}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] List launcher products.","tags":["Launcher Admin / Products"]},"post":{"description":"Creates a new launcher product. If bannerKey or imageKeys are provided, presigned R2 PUT URLs are returned in uploadUrls. The client uploads image files directly to those URLs at its own pace.","operationId":"LauncherProductsAdminController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLauncherProductDto"}}}},"responses":{"201":{"description":"Product created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LauncherProductWithUploadUrlsResponseDto"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"A product with this slug already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Create a launcher product.","tags":["Launcher Admin / Products"]}},"/api/v1/admin/launcher/products/{slug}":{"get":{"description":"Returns the product matching the given slug. Includes archived products.","operationId":"LauncherProductsAdminController_getBySlug","parameters":[{"name":"slug","required":true,"in":"path","description":"Product slug (e.g. \"main-game\").","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/LauncherProductAdminResponseDto"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Product not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get a launcher product by slug.","tags":["Launcher Admin / Products"]},"patch":{"description":"Updates a non-archived launcher product. slug is immutable. Presigned R2 PUT URLs are returned in uploadUrls for any image keys present in the request body.","operationId":"LauncherProductsAdminController_update","parameters":[{"name":"slug","required":true,"in":"path","description":"Product slug.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLauncherProductDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/LauncherProductWithUploadUrlsResponseDto"}}}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Product not found or is archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update a launcher product.","tags":["Launcher Admin / Products"]}},"/api/v1/admin/launcher/products/{slug}/archive":{"post":{"description":"Soft-deletes the product and all its branches in a single transaction. No data is permanently deleted. Archived products are excluded from the public catalog.","operationId":"LauncherProductsAdminController_archive","parameters":[{"name":"slug","required":true,"in":"path","description":"Product slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"Product archived.","content":{"application/json":{"schema":{"properties":{"archivedAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Product not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Product is already archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Archive a launcher product.","tags":["Launcher Admin / Products"]}},"/api/v1/admin/launcher/products/{slug}/unarchive":{"post":{"description":"Restores the product and all its branches. Note: restores ALL branches belonging to the product, including any individually archived before the product was archived.","operationId":"LauncherProductsAdminController_unarchive","parameters":[{"name":"slug","required":true,"in":"path","description":"Product slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"Product restored.","content":{"application/json":{"schema":{"properties":{"restoredAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Admin access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Product not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Product is not archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[ADMIN] Unarchive a launcher product.","tags":["Launcher Admin / Products"]}},"/auth/sso/{provider}/start":{"get":{"description":"Redirects the browser to the provider authorization page. After consent the provider redirects to the backend callback, which redirects to the client's SSO callback page with a one-time code.","operationId":"SsoController_start","parameters":[{"name":"provider","required":true,"in":"path","schema":{"type":"string"}},{"name":"client","required":true,"in":"query","schema":{"type":"string"}},{"name":"return_to","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"400":{"description":"Unknown provider or client."}},"summary":"Start an SSO sign-in flow.","tags":["SSO"]}},"/auth/sso/{provider}/callback":{"get":{"description":"Handles the provider redirect and forwards the browser to the client callback page with either a one-time code or an error.","operationId":"SsoController_callback","parameters":[{"name":"provider","required":true,"in":"path","schema":{"type":"string"}},{"name":"state","required":false,"in":"query","schema":{"type":"string"}},{"name":"code","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"SSO provider OAuth callback.","tags":["SSO"]}},"/auth/sso/exchange":{"post":{"description":"Returns the same token payload as /auth/login for returning users, or a completion_required payload for first-time SSO signups.","operationId":"SsoController_exchange","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SsoExchangeRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SsoExchangeResponseDto"}}}},"400":{"description":"Invalid or expired code."}},"summary":"Exchange a one-time SSO code for tokens.","tags":["SSO"]}},"/auth/sso/complete":{"post":{"description":"Creates the account (username, EULA/privacy acceptance and invite code follow the same rules as /auth/register) and returns tokens, or verification_required when the email still needs verifying.","operationId":"SsoController_complete","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SsoCompleteRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SsoExchangeResponseDto"}}}},"400":{"description":"Invalid completion token, invite code or EULA acceptance."}},"summary":"Finish a first-time SSO signup.","tags":["SSO"]}},"/auth/sso/identities":{"get":{"operationId":"SsoController_identities","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SsoIdentitiesResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"List the linked SSO identities of the user.","tags":["SSO"]}},"/auth/sso/{provider}/link/start":{"post":{"description":"Returns the provider authorization URL. The callback redirects to the client callback page with link=success or an error.\n\nClient tokens are not allowed on this route: This route is not supported at this time.","operationId":"SsoController_linkStart","parameters":[{"name":"provider","required":true,"in":"path","schema":{"type":"string"}},{"name":"client","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SsoStartLinkResponseDto"}}}},"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Start linking an SSO provider to the current account.","tags":["SSO","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported at this time."}}},"/auth/sso/{provider}":{"delete":{"description":"Refused when it is the last sign-in method of a passwordless account.\n\nClient tokens are not allowed on this route: This route is not supported at this time.","operationId":"SsoController_unlink","parameters":[{"name":"provider","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"403":{"description":"Client tokens are not allowed on this route."},"406":{"description":"Client token version is outdated."}},"security":[{"bearer":[]}],"summary":"Unlink an SSO provider from the current account.","tags":["SSO","No Client Token Support"],"x-client-token-support":{"supported":false,"description":"Client tokens are not allowed on this route: This route is not supported at this time."}}},"/api/v1/runtime/uploads":{"post":{"operationId":"InstantRuntimeController_createUploads","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRuntimeUploadRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Presign write-once uploads for version-pinned runtime resources.","tags":["Instant Runtime"]}},"/api/v1/universal-items/inventory/{instanceId}/instance":{"get":{"operationId":"ItemInstancesController_get","parameters":[{"name":"instanceId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"One owned copy of an item: its owner, installed add-ons, net worth, provenance and listing state.","tags":["item-instances"]}},"/api/v1/achievements/worlds/{worldId}":{"get":{"operationId":"AchievementsController_listWorld","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"List a world's registered achievements.","tags":["achievements"]},"post":{"operationId":"AchievementsController_registerForWorld","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CreateAchievementRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Register a new achievement for a world (world owner). Mints its soulbound item from `image` (2D icon, required) + optional `mesh` (GLB plaque).","tags":["achievements"]}},"/api/v1/achievements/worlds/{worldId}/me":{"get":{"operationId":"AchievementsController_worldProgress","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"The viewer's progress in a world (\"7/12 earned here\").","tags":["achievements"]}},"/api/v1/achievements/worlds/{worldId}/top-players":{"get":{"operationId":"AchievementsController_worldTopPlayers","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"A world's top players, ranked by achievement score + completion.","tags":["achievements"]}},"/api/v1/achievements/me":{"get":{"operationId":"AchievementsController_listMine","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List the signed-in user’s earned achievements.","tags":["achievements"]}},"/api/v1/achievements/me/summary":{"get":{"operationId":"AchievementsController_mySummary","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"The signed-in user’s gamerscore + earned count.","tags":["achievements"]}},"/api/v1/achievements/users/{userId}/summary":{"get":{"operationId":"AchievementsController_userSummary","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"A user’s gamerscore + earned count (profile stat).","tags":["achievements"]}},"/api/v1/achievements/users/{userId}":{"get":{"operationId":"AchievementsController_listForUser","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List a user’s earned achievements (profile showcase).","tags":["achievements"]}},"/api/v1/achievements/{id}":{"get":{"operationId":"AchievementsController_detail","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Achievement detail (for the detail view).","tags":["achievements"]},"patch":{"operationId":"AchievementsController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAchievementRequestDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Update an achievement (world owner).","tags":["achievements"]}},"/api/v1/achievements/{id}/friends":{"get":{"operationId":"AchievementsController_friendsWithIt","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Friends of the viewer who also hold this achievement.","tags":["achievements"]}},"/api/v1/achievements/{id}/trophy":{"put":{"operationId":"AchievementsController_attachTrophy","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Attach or replace an achievement's bespoke 3D trophy (world owner). Send `mesh` (a .glb). Replaces the default plaque.","tags":["achievements"]},"delete":{"operationId":"AchievementsController_resetTrophy","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Drop a bespoke trophy and fall back to the default plaque with the achievement's 2D icon baked into it (world owner).","tags":["achievements"]}},"/api/v1/achievements/{id}/icon":{"put":{"operationId":"AchievementsController_replaceIcon","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Replace an achievement's 2D graphic (world owner). Send `image`. Re-bakes the default plaque unless a bespoke trophy is attached.","tags":["achievements"]}},"/api/v1/achievements/{id}/claim":{"post":{"deprecated":true,"description":"Always 410 Gone. A world running in the player’s browser cannot attest that the player earned anything. Achievements are awarded by the authoritative multiplayer room (the `awardAchievement` effect) or by server-evaluated `criteria` — see an achievement’s `unlockMode`.","operationId":"AchievementsController_claimRemoved","parameters":[],"responses":{"201":{"description":""}},"summary":"REMOVED — client-attested achievement claims are not accepted.","tags":["achievements"]}},"/api/v1/achievements/{id}/admin/grant":{"post":{"operationId":"AchievementsController_adminGrant","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantAchievementRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Admin: manually grant an achievement to a user.","tags":["achievements"]}},"/api/v1/achievements/admin/rollup":{"post":{"operationId":"AchievementsController_adminRollup","parameters":[],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Admin: run the achievement rarity rollup now.","tags":["achievements"]}},"/api/v1/achievements/admin/criteria-sweep":{"post":{"description":"The same bounded sweep the hourly cron runs, but across EVERY signal — the manual net. The cron itself only sweeps the aggregate signals (`analytics`, `playtime`); `datastore` and `iwp` unlocks are evaluated within seconds of the write or purchase that earned them.","operationId":"AchievementsController_adminCriteriaSweep","parameters":[],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Admin: run the server-evaluated criteria sweep now.","tags":["achievements"]}},"/api/v1/dreamer/items/quote":{"get":{"description":"Read-only. Reserves nothing and mints no quote token — the item lanes meter each stage as they run, and this reads the same pricing config those charges use. Excludes revisions, which are unknowable up front, so callers must show it as the cost of one clean run rather than a cap.","operationId":"DreamerController_quoteItemGeneration","parameters":[{"name":"kind","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"What one clean item generation costs, per stage, before the creator commits (HYPR-5117).","tags":["Dreamer"]}},"/api/v1/dreamer/generate":{"post":{"operationId":"DreamerController_generate","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DreamerGenerateRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Start a Dreamer generation job for a universal avatar or home item.","tags":["Dreamer"]}},"/api/v1/dreamer/generate-from-reference":{"post":{"description":"The uploaded image passes the same bounded decode, geometric slicing, shuffled semantic orientation gate, durable workspace mirror, and concept approval gate as a generated sheet. It does not invoke or charge the image provider. After approval, the existing mesh, texture, humanoid rig/LOD, thumbnail, publish, and Vault pipeline is unchanged.","operationId":"DreamerController_generateFromReference","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["prompt","referenceSheet"],"properties":{"prompt":{"type":"string","maxLength":3000},"additionalPrompt":{"type":"string","maxLength":800},"title":{"type":"string","maxLength":100},"targetPolycount":{"type":"integer","minimum":1000},"projectId":{"type":"string","format":"uuid"},"referenceSheet":{"type":"string","format":"binary","description":"PNG, JPEG, or WebP containing one real 2x2 or 1x4 FRONT/BACK/LEFT/RIGHT character sheet."}}}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Start the normal Dreamer character pipeline from a creator-supplied four-view reference sheet.","tags":["Dreamer"]}},"/api/v1/dreamer/jobs":{"get":{"description":"This route used to 404, which left a creator no way to enumerate their own work — so a generation that failed without surfacing its job id produced a LIX charge with no identifier attached, unauditable by anyone. Covers both interactive Dreamer jobs and standalone asset generations. Every row names its LIX spend, any LIX still held, the gate it is parked at, and the endpoints that advance it. Read-only.","operationId":"DreamerController_listJobs","parameters":[{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Skip this many jobs (newest first).","schema":{"minimum":0,"type":"number"}},{"name":"state","required":false,"in":"query","description":"Narrow to a lifecycle state. `unfinished` is every job that has neither published nor died — including one parked at an approval gate, which is the state that looks like nothing happened.","schema":{"default":"all","type":"string","enum":["all","unfinished","failed","published","awaiting_approval"]}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List the caller's generation jobs, newest first.","tags":["Dreamer"]}},"/api/v1/dreamer/jobs/{jobId}":{"get":{"operationId":"DreamerController_getJob","parameters":[{"name":"jobId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Read a Dreamer job owned by the caller.","tags":["Dreamer"]}},"/api/v1/dreamer/jobs/{jobId}/approve":{"post":{"operationId":"DreamerController_approve","parameters":[{"name":"jobId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DreamerApproveRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Approve a Dreamer approval gate (concept|preview) and advance the job.","tags":["Dreamer"]}},"/api/v1/dreamer/jobs/{jobId}/revise":{"post":{"operationId":"DreamerController_revise","parameters":[{"name":"jobId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DreamerReviseRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Revise a gated stage with new guidance (charges a fresh regeneration).","tags":["Dreamer"]}},"/api/v1/dreamer/jobs/{jobId}/retry":{"post":{"operationId":"DreamerController_retry","parameters":[{"name":"jobId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Retry a failed Dreamer job, resuming from the mesh phase (concept kept) or rebuilding from the concept.","tags":["Dreamer"]}},"/api/v1/dreamer/jobs/{jobId}/publish":{"post":{"operationId":"DreamerController_publishJob","parameters":[{"name":"jobId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DreamerPublishJobRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Publish a completed Dreamer-generated mesh through universal-item verification and storage.","tags":["Dreamer"]}},"/api/v1/dreamer/jobs/{jobId}/thumbnail":{"post":{"operationId":"DreamerController_setJobThumbnail","parameters":[{"name":"jobId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Retry the canonical thumbnail from the job's validated final mesh. Legacy uploaded capture bytes are ignored.","tags":["Dreamer"]}},"/api/v1/dreamer/publish-upload":{"post":{"operationId":"DreamerController_publishUpload","parameters":[],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Dreamer upload/publish facade for local avatar or home-item GLBs.","tags":["Dreamer"]}},"/api/v1/dreamer/assets/capabilities":{"get":{"operationId":"DreamerController_assetGenerationCapabilities","parameters":[],"responses":{"200":{"description":""}},"summary":"List the asset generation categories and options available on this server.","tags":["Dreamer"]}},"/api/v1/dreamer/assets/references":{"post":{"operationId":"DreamerController_stageAssetGenerationReference","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["kind","idempotencyKey","references"],"properties":{"kind":{"type":"string","enum":["character","prop","texture","material"]},"idempotencyKey":{"type":"string","minLength":8,"maxLength":96},"references":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"string","format":"binary"}}}}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Validate and temporarily stage creator-owned visual generation references.","tags":["Dreamer"]}},"/api/v1/dreamer/assets/quotes":{"post":{"operationId":"DreamerController_quoteAssetGeneration","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DreamerAssetGenerateRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Validate an asset generation draft and return its exact, short-lived LIX quote.","tags":["Dreamer"]}},"/api/v1/dreamer/assets/generations":{"post":{"operationId":"DreamerController_startQuotedAssetGeneration","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartQuotedAssetGenerationRequestDto"}}}},"responses":{"202":{"description":""}},"security":[{"bearer":[]}],"summary":"Reserve the exact accepted quote and idempotently start its asset generation job.","tags":["Dreamer"]}},"/api/v1/dreamer/assets/jobs":{"get":{"operationId":"DreamerController_listAssetJobs","parameters":[{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"updatedAfter","required":false,"in":"query","description":"Return only jobs changed after this timestamp. Use the response serverTime for the next safe poll.","schema":{"type":"string"}},{"name":"kind","required":false,"in":"query","schema":{"type":"string","enum":["prop","character","texture","material","audio","gaussian_splat"]}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List the caller’s standalone asset generation jobs for Manage polling.","tags":["Dreamer"]}},"/api/v1/dreamer/assets/generate":{"post":{"description":"Starts the same LIX-metered pipeline used by world-generation workers. Successful jobs are registered in Vault unless the creator explicitly opted out. Materials are a separate validated PBR-bundle contract; this endpoint does not pretend a flat image is a material.","operationId":"DreamerController_generateAsset","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DreamerAssetGenerateRequestDto"}}}},"responses":{"202":{"description":""}},"security":[{"bearer":[]}],"summary":"Generate a standalone image, prop, PBR material, sound, or experimental Gaussian-splat environment for a creator or client-token caller.","tags":["Dreamer"]}},"/api/v1/dreamer/assets/jobs/{jobId}":{"get":{"operationId":"DreamerController_getAssetJob","parameters":[{"name":"jobId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Poll a standalone image generation job owned by the caller.","tags":["Dreamer"]}},"/api/v1/dreamer/jobs/{jobId}/assets/{asset}":{"get":{"operationId":"DreamerController_asset","parameters":[{"name":"jobId","required":true,"in":"path","schema":{"type":"string"}},{"name":"asset","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Serve a generated Dreamer temp asset.","tags":["Dreamer"]}},"/api/v1/dreamer/voices":{"get":{"description":"Returns a cached, stable projection of provider-default voices for authenticated frontend, CLI, SDK, and MCP callers. Provider credentials, voice administration, and voice cloning are never exposed.","operationId":"DreamerVoicesController_list","parameters":[{"name":"search","required":false,"in":"query","description":"Searches voice name, description, labels, and category.","schema":{"maxLength":100,"type":"string"}},{"name":"pageSize","required":false,"in":"query","description":"Maximum voices returned in this page.","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"pageToken","required":false,"in":"query","description":"Opaque token returned as pageInfo.nextPageToken by the previous page.","schema":{"maxLength":512,"type":"string"}},{"name":"category","required":false,"in":"query","description":"Optional safe category filter. Cloned and generated voices are not exposed.","schema":{"type":"string","enum":["premade","professional"]}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List or search safe text-to-speech voices.","tags":["Dreamer"]}},"/api/v1/lix-billing/balance":{"get":{"description":"`available` is spendable right now. `held` is escrowed by open generation reservations — a reservation moves LIX out of the wallet before the work runs and settles it at the real cost afterwards, so `available + held = total` and nothing is counted twice. `holds[]` itemizes what is holding the money, so a generation that stranded LIX is visible instead of merely missing. Amounts are LIX as decimals at the wallet's 4-dp precision, never minor units.","operationId":"LixBillingController_balance","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"The caller's LIX balance: available, held and total.","tags":["LIX Billing"]}},"/api/v1/lix-billing/transactions":{"get":{"description":"Keyset-paginated (cursor/nextCursor). Every row carries a backend-owned `label` and, once the generation produced something, the asset name and a deep link — resolved by the same joins the wallet history uses, so a generation cannot be named one way here and another way there. Pass generationsOnly=true to drop zero-amount bookkeeping rows.","operationId":"LixBillingController_listTransactions","parameters":[{"name":"projectId","required":false,"in":"query","schema":{"type":"string"}},{"name":"action","required":false,"in":"query","schema":{"type":"string","enum":["text_gen","image_gen","mesh_gen","texture_gen","voice_gen","rigging","regeneration","sandbox_seconds","publish_build","optimization","session_start"]}},{"name":"generationsOnly","required":false,"in":"query","description":"Only rows that actually charged LIX for generation work — drops the free session_start affordability gate and any other zero-amount bookkeeping row.","schema":{"default":false,"type":"boolean"}},{"name":"from","required":false,"in":"query","description":"ISO timestamp lower bound.","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"ISO timestamp upper bound.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":100,"default":20,"type":"number"}},{"name":"cursor","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List the caller's creation-billing transactions (itemized).","tags":["LIX Billing"]}},"/api/v1/lix-billing/usage-summary":{"get":{"description":"Powers the Create/Manage \"LIX Usage\" panel. One grouped SQL aggregate per call over the existing (user_id, created_at) index, cached briefly per user — no per-action query fan-out and no row scanning in JS. Windows are ROLLING (day = last 24h, week = 7d, month = 30d); periodStart/periodEnd state the exact bounds so no timezone is implied.","operationId":"LixBillingController_usageSummary","parameters":[{"name":"window","required":false,"in":"query","description":"Rolling window: day = last 24h, week = last 7d, month = last 30d, all = account lifetime.","schema":{"default":"day","type":"string","enum":["day","week","month","all"]}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Creation LIX spend for a rolling window, broken down by action.","tags":["LIX Billing"]}},"/api/v1/lix-billing/usage":{"get":{"operationId":"LixBillingController_usage","parameters":[{"name":"from","required":false,"in":"query","description":"ISO timestamp lower bound.","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"ISO timestamp upper bound.","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Account-wide creation LIX usage summary.","tags":["LIX Billing"]}},"/api/v1/lix-billing/usage/by-project":{"get":{"operationId":"LixBillingController_usageByProject","parameters":[{"name":"from","required":false,"in":"query","description":"ISO timestamp lower bound.","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"ISO timestamp upper bound.","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Per-project creation LIX usage breakdown.","tags":["LIX Billing"]}},"/api/v1/lix-billing/admin/pricing":{"get":{"operationId":"LixBillingController_readPricing","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] The active generation price list, with its version, checksum and source.","tags":["LIX Billing"]},"post":{"operationId":"LixBillingController_publishPricing","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishPricingConfigRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Publish a new generation price list. Rejected if any price would sell below vendor cost at the floor LIX value.","tags":["LIX Billing"]}},"/api/v1/lix-billing/admin/pricing/versions":{"get":{"operationId":"LixBillingController_listPricingVersions","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Every published price list, newest first — what rate applied when.","tags":["LIX Billing"]}},"/api/v1/projects":{"post":{"operationId":"ProjectsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"tags":["projects"]},"get":{"operationId":"ProjectsController_list","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"tags":["projects"]}},"/api/v1/projects/{id}":{"get":{"operationId":"ProjectsController_get","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"tags":["projects"]},"patch":{"operationId":"ProjectsController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProjectDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"tags":["projects"]},"delete":{"operationId":"ProjectsController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"bearer":[]}],"tags":["projects"]}},"/api/v1/projects/{id}/versions":{"get":{"operationId":"ProjectsController_listVersions","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"tags":["projects"]},"post":{"operationId":"ProjectsController_createVersion","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVersionDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"tags":["projects"]}},"/api/v1/projects/{id}/assets/upload-url":{"post":{"operationId":"ProjectsController_createAssetUploadUrl","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAssetUploadUrlDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"tags":["projects"]}},"/api/v1/projects/{id}/assets":{"post":{"operationId":"ProjectsController_registerAsset","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterAssetDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"tags":["projects"]},"get":{"operationId":"ProjectsController_listAssets","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"tags":["projects"]}},"/api/v1/projects/{id}/assets/{assetId}":{"delete":{"operationId":"ProjectsController_deleteAsset","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"bearer":[]}],"tags":["projects"]}},"/api/v1/projects/{id}/publish":{"post":{"operationId":"ProjectsController_publish","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"tags":["projects"]}},"/api/v1/vault/assets":{"get":{"description":"Hybrid semantic plus indexed lexical retrieval over title/description/tags, combined with measured quality, performance, reuse and popularity. Structured kind, compatibility, performance and license filters are hard predicates and are never weakened by ranking. If query embeddings are unavailable, the endpoint remains available as lexical full-text search and reports that fallback in selectionExplanation. Anonymous callers see public assets; an authenticated caller additionally sees their own assets at any visibility, with `visibility` on every row.","operationId":"VaultAssetsController_search","parameters":[{"name":"q","required":false,"in":"query","description":"Hybrid semantic + lexical query over title, description, tags, kind and compatibility. Structured filters remain authoritative.","schema":{"type":"string"}},{"name":"match","required":false,"in":"query","description":"What `q` DOES to the result set. `recall` (the default, and what every existing agent caller gets) treats `q` as a RANKING input: semantic and lexical candidates are unioned and ordered, so an agent asking for \"something rusty and industrial\" always gets its best available options rather than an empty answer. `narrow` treats `q` as a FILTER: only rows that textually match are returned, and `GET /vault/assets/facets` counts the same narrowed set, so a chip number survives being clicked. Browse UIs want `narrow` — a person searching \"brick\" reads a humanoid character underneath the bricks as broken, however well it is ranked. A query that matches nothing returns nothing; `narrow` never falls back to the unfiltered library.","schema":{"default":"recall","type":"string","enum":["recall","narrow"]}},{"name":"kind","required":false,"in":"query","description":"Resource kinds to include. Repeat or comma-separate.","schema":{"type":"array","items":{"type":"string","enum":["prop","character","animation","audio","texture","material","environment","terrain","vfx","decal","sky","gaussian_splat","scene","interactive_item","unreal_package"]}}},{"name":"subtype","required":false,"in":"query","description":"Typed subtype such as emote, static-prop, pbr-material, heightfield, or gaussian-splat. Emotes are executable interactive_item definitions; raw motion clips remain kind=animation.","schema":{"type":"string"}},{"name":"scope","required":false,"in":"query","description":"Gaussian-splat reuse scope.","schema":{"type":"string","enum":["object","environment"]}},{"name":"format","required":false,"in":"query","description":"Primary artifact format, e.g. glb, spz, helix-material, helix-scene, hdr, or exr.","schema":{"type":"string"}},{"name":"performanceTier","required":false,"in":"query","description":"Measured runtime-cost tier. Quality is never fabricated.","schema":{"type":"string","enum":["mobile","desktop","cinematic","unknown"]}},{"name":"rank","required":false,"in":"query","description":"Agent ranking strategy. relevance uses documented semantic/lexical/quality/performance/reuse/popularity weights; performance and reuse keep their named signal primary.","schema":{"default":"relevance","type":"string","enum":["relevance","performance","reuse"]}},{"name":"sort","required":false,"in":"query","description":"BROWSE ordering, for a human scanning a catalogue rather than an agent asking a question. Takes precedence over `rank` when both are present: `rank` chooses which signals decide relevance, `sort` says relevance is not what the reader wants. Omit it to keep the agent default. Every ordering ends on a deterministic id tiebreak, so page 5 of a sort is stable.","schema":{"type":"string","enum":["recent","popular","name"]}},{"name":"skeleton","required":false,"in":"query","description":"Only assets rigged to this standard skeleton. Meaningful for characters and animations.","schema":{"type":"string","enum":["humanoid","quadruped"]}},{"name":"engine","required":false,"in":"query","description":"Only assets usable in this runtime.","schema":{"type":"string","enum":["web","unreal"]}},{"name":"license","required":false,"in":"query","schema":{"type":"string","enum":["helix_standard","cc0","cc_by","all_rights_reserved"]}},{"name":"official","required":false,"in":"query","description":"TRUE narrows to platform-vouched (official) assets — the calibrated, convention-correct tier. Try official first and widen only when it has no fit; FALSE narrows to community assets; omit for everything. A preference filter, never a gate.","schema":{"type":"boolean"}},{"name":"source","required":false,"in":"query","description":"How the asset entered the Vault. `world_generation` isolates agent-produced assets.","schema":{"type":"string","enum":["manual","dreamer","world_generation","import"]}},{"name":"origin","required":false,"in":"query","description":"THE TRUST AXIS. `generated` = produced by a HELIX pipeline, and therefore moderated by that generator upstream; `uploaded` = a file a user supplied, which reaches this library through an open endpoint with no scanner of its own. Filter to `generated` when a consumer needs to rely on upstream moderation. Distinct from `source`, which names the pipeline and will keep gaining values.","schema":{"type":"string","enum":["generated","uploaded"]}},{"name":"creatorId","required":false,"in":"query","description":"Only this creator’s assets.","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"Creator-scoped/public Vault results. For subtype=emote, metadata.interactive.emote exposes immutable role-addressed animation/audio references and playback/join facts.","content":{"application/json":{"schema":{"type":"object","required":["items","totalItems"],"properties":{"totalItems":{"type":"number"},"items":{"type":"array","items":{"type":"object","required":["assetId","kind","visibility","currentVersion","metadata"],"properties":{"assetId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["prop","character","animation","audio","texture","material","environment","terrain","vfx","decal","sky","gaussian_splat","scene","interactive_item","unreal_package"]},"visibility":{"type":"string","enum":["public","private","held"]},"currentVersion":{"type":"integer","minimum":1},"metadata":{"type":"object","properties":{"subtype":{"type":"string","example":"emote"},"interactive":{"type":"object","properties":{"emote":{"type":"object","properties":{"playback":{"type":"string","enum":["loop","oneshot"]},"joinMode":{"type":"string","enum":["none","partner"]},"participantCount":{"type":"integer","minimum":1},"assets":{"type":"object","description":"Role-addressed initiator/joiner/intro/outro/audio references. Each entry pins assetId, version, checksumSha256, kind, durationSeconds, rig, skeleton and engines.","additionalProperties":true}}}}}},"additionalProperties":true}},"additionalProperties":true}}}}}}}},"security":[{"bearer":[]}],"summary":"Search Vault assets (creator- and agent-facing).","tags":["Vault"]},"post":{"operationId":"VaultAssetsController_publish","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["payload","artifact"],"properties":{"payload":{"type":"string","description":"JSON-encoded Vault publish request."},"artifact":{"type":"string","format":"binary"},"skyBackdrop":{"type":"string","format":"binary","description":"Required for sky descriptors: the checksum-bound 2:1 web PNG stored with the immutable Vault version."},"skyLighting":{"type":"string","format":"binary","description":"Required for sky descriptors: the checksum-bound HDR or EXR image-based lighting source stored with the immutable Vault version."}}}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Publish a resource (mesh, character, animation, audio, texture or validated material manifest) to the Vault.","tags":["Vault"]}},"/api/v1/vault/assets/facets":{"get":{"description":"Counts are computed over every active filter EXCEPT `kind`, so a selected kind does not zero its peers. Served by a single grouped aggregate rather than one list request per kind.","operationId":"VaultAssetsController_facets","parameters":[{"name":"q","required":false,"in":"query","description":"Hybrid semantic + lexical query over title, description, tags, kind and compatibility. Structured filters remain authoritative.","schema":{"type":"string"}},{"name":"match","required":false,"in":"query","description":"What `q` DOES to the result set. `recall` (the default, and what every existing agent caller gets) treats `q` as a RANKING input: semantic and lexical candidates are unioned and ordered, so an agent asking for \"something rusty and industrial\" always gets its best available options rather than an empty answer. `narrow` treats `q` as a FILTER: only rows that textually match are returned, and `GET /vault/assets/facets` counts the same narrowed set, so a chip number survives being clicked. Browse UIs want `narrow` — a person searching \"brick\" reads a humanoid character underneath the bricks as broken, however well it is ranked. A query that matches nothing returns nothing; `narrow` never falls back to the unfiltered library.","schema":{"default":"recall","type":"string","enum":["recall","narrow"]}},{"name":"kind","required":false,"in":"query","description":"Resource kinds to include. Repeat or comma-separate.","schema":{"type":"array","items":{"type":"string","enum":["prop","character","animation","audio","texture","material","environment","terrain","vfx","decal","sky","gaussian_splat","scene","interactive_item","unreal_package"]}}},{"name":"subtype","required":false,"in":"query","description":"Typed subtype such as emote, static-prop, pbr-material, heightfield, or gaussian-splat. Emotes are executable interactive_item definitions; raw motion clips remain kind=animation.","schema":{"type":"string"}},{"name":"scope","required":false,"in":"query","description":"Gaussian-splat reuse scope.","schema":{"type":"string","enum":["object","environment"]}},{"name":"format","required":false,"in":"query","description":"Primary artifact format, e.g. glb, spz, helix-material, helix-scene, hdr, or exr.","schema":{"type":"string"}},{"name":"performanceTier","required":false,"in":"query","description":"Measured runtime-cost tier. Quality is never fabricated.","schema":{"type":"string","enum":["mobile","desktop","cinematic","unknown"]}},{"name":"rank","required":false,"in":"query","description":"Agent ranking strategy. relevance uses documented semantic/lexical/quality/performance/reuse/popularity weights; performance and reuse keep their named signal primary.","schema":{"default":"relevance","type":"string","enum":["relevance","performance","reuse"]}},{"name":"sort","required":false,"in":"query","description":"BROWSE ordering, for a human scanning a catalogue rather than an agent asking a question. Takes precedence over `rank` when both are present: `rank` chooses which signals decide relevance, `sort` says relevance is not what the reader wants. Omit it to keep the agent default. Every ordering ends on a deterministic id tiebreak, so page 5 of a sort is stable.","schema":{"type":"string","enum":["recent","popular","name"]}},{"name":"skeleton","required":false,"in":"query","description":"Only assets rigged to this standard skeleton. Meaningful for characters and animations.","schema":{"type":"string","enum":["humanoid","quadruped"]}},{"name":"engine","required":false,"in":"query","description":"Only assets usable in this runtime.","schema":{"type":"string","enum":["web","unreal"]}},{"name":"license","required":false,"in":"query","schema":{"type":"string","enum":["helix_standard","cc0","cc_by","all_rights_reserved"]}},{"name":"official","required":false,"in":"query","description":"TRUE narrows to platform-vouched (official) assets — the calibrated, convention-correct tier. Try official first and widen only when it has no fit; FALSE narrows to community assets; omit for everything. A preference filter, never a gate.","schema":{"type":"boolean"}},{"name":"source","required":false,"in":"query","description":"How the asset entered the Vault. `world_generation` isolates agent-produced assets.","schema":{"type":"string","enum":["manual","dreamer","world_generation","import"]}},{"name":"origin","required":false,"in":"query","description":"THE TRUST AXIS. `generated` = produced by a HELIX pipeline, and therefore moderated by that generator upstream; `uploaded` = a file a user supplied, which reaches this library through an open endpoint with no scanner of its own. Filter to `generated` when a consumer needs to rely on upstream moderation. Distinct from `source`, which names the pipeline and will keep gaining values.","schema":{"type":"string","enum":["generated","uploaded"]}},{"name":"creatorId","required":false,"in":"query","description":"Only this creator’s assets.","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"counts":{"type":"object","additionalProperties":{"type":"number"}}}}}}}},"security":[{"bearer":[]}],"summary":"Per-kind counts for the current Vault filters.","tags":["Vault"]}},"/api/v1/vault/assets/{assetId}":{"get":{"description":"A creator can always read their own asset, whatever its visibility; the row's `visibility` reports the state. Non-public assets remain hidden from everyone else.","operationId":"VaultAssetsController_getAsset","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Read one Vault asset and resolve its served artifact.","tags":["Vault"]},"patch":{"description":"Annotations only. The published artifact of every version is immutable and is not touched.","operationId":"VaultAssetsController_updateMetadata","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVaultAssetRequestDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Edit a published asset’s title, description, tags or rating.","tags":["Vault"]},"delete":{"operationId":"VaultAssetsController_deleteOwnedAsset","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"409":{"description":"The asset is in use by an active world or linked product and cannot be deleted."}},"security":[{"bearer":[]}],"summary":"Delete an unused owned asset while retaining an inaccessible immutable tombstone.","tags":["Vault"]}},"/api/v1/vault/assets/{assetId}/official":{"patch":{"description":"A discovery preference, never a gate — community assets stay fully usable. Platform-admin publishes receive the mark automatically at publish time.","operationId":"VaultAssetsController_setOfficial","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetVaultAssetOfficialRequestDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"ADMIN: set or clear the platform `official` mark on a Vault asset.","tags":["Vault"]}},"/api/v1/vault/assets/{assetId}/lifecycle":{"get":{"operationId":"VaultAssetsController_lifecycle","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Read the server-authoritative publish, privacy and deletion state for an owned Vault asset.","tags":["Vault"]}},"/api/v1/vault/assets/{assetId}/publish":{"post":{"operationId":"VaultAssetsController_publishOwnedAsset","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Publish an owned private asset to Vault.","tags":["Vault"]}},"/api/v1/vault/assets/{assetId}/make-private":{"post":{"operationId":"VaultAssetsController_makeOwnedAssetPrivate","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"409":{"description":"The asset is in use by an active world or linked product and cannot be made private."}},"security":[{"bearer":[]}],"summary":"Unpublish an owned Vault asset by making it private.","tags":["Vault"]}},"/api/v1/vault/assets/{assetId}/product":{"post":{"description":"Creator-only. `kind` must be `prop`, or `emote` when the definition declares only an emote; `usage` must match what the definition declares (held/emote → hold, anchored → place or display).","operationId":"VaultAssetsController_publishInteractiveItemProduct","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUniversalItemRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/UniversalItemResponseDto"}}}}}},"409":{"description":"The definition is not public, or has been deleted."}},"security":[{"bearer":[]}],"summary":"List an owned interactive-item definition as a universal item.","tags":["Vault"]}},"/api/v1/vault/assets/{assetId}/versions":{"get":{"operationId":"VaultAssetsController_versions","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Version history. Immutable, newest first.","tags":["Vault"]},"post":{"operationId":"VaultAssetsController_addVersion","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["artifact","expectedCurrentVersion","expectedCurrentChecksumSha256"],"properties":{"notes":{"type":"string"},"expectedCurrentVersion":{"type":"integer","minimum":1,"description":"Compare-and-set precondition: the currently served immutable version."},"expectedCurrentChecksumSha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Compare-and-set precondition: checksum of the currently served primary artifact."},"metadata":{"type":"string","description":"Optional JSON-encoded version declarations. Animation versions may replace rootMotion, loop, durationSeconds, frameCount, framesPerSecond and rig; measured artifact facts are always recomputed server-side."},"artifact":{"type":"string","format":"binary"},"skyBackdrop":{"type":"string","format":"binary","description":"Required when versioning a sky descriptor; checksum must match its declared web rendition."},"skyLighting":{"type":"string","format":"binary","description":"Required when versioning a sky descriptor; HDR/EXR checksum and measured dimensions must match its declared lighting source."}}}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Publish a new immutable version and serve it.","tags":["Vault"]}},"/api/v1/vault/assets/{assetId}/revert/{version}":{"post":{"operationId":"VaultAssetsController_revert","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}},{"name":"version","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Roll back to a previously published version.","tags":["Vault"]}},"/api/v1/vault/scene-items/{assetId}/{revision}":{"get":{"description":"The Scene pin names a Vault interactive-item descriptor, not raw GLB bytes. This endpoint verifies the definition checksum and optional Marketplace product binding, then returns the exact public Web mesh pin selected by the definition.","operationId":"VaultAssetsController_resolveSceneItemDefinition","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}},{"name":"revision","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"summary":"Resolve an immutable Scene v2 universal-item definition to its Web rendition.","tags":["Vault"]}},"/api/v1/vault/assets/{assetId}/versions/{version}/artifact":{"get":{"description":"Unlike asset detail, this never substitutes the current version. Scene v2 uses it for pinned Sky lighting and other version-owned companions, then verifies every returned checksum.","operationId":"VaultAssetsController_resolveVersionArtifact","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}},{"name":"version","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Resolve one immutable Vault version and its exact companion artifacts.","tags":["Vault"]}},"/api/v1/vault/assets/{assetId}/versions/{version}/content":{"get":{"description":"Scene v2 uses this byte endpoint instead of trusting CDN or filename MIME inference. An optional role selects one immutable companion owned by the same primary revision.","operationId":"VaultAssetsController_serveVersionArtifactContent","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}},{"name":"version","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Serve one integrity-pinned Vault version artifact with exact MIME.","tags":["Vault"]}},"/api/v1/vault/assets/{assetId}/download":{"get":{"description":"Unconditional today. The seam where an entitlement check lands later, so no caller has to change when it does.","operationId":"VaultAssetsController_download","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Redirect (302) to the artifact for a Vault asset.","tags":["Vault"]}},"/api/v1/vault/artifacts/{key}":{"get":{"operationId":"VaultAssetsController_serveLocal","parameters":[],"responses":{"200":{"description":""}},"summary":"Serve a locally-stored Vault artifact (dev only).","tags":["Vault"]}},"/api/v1/vault/skeletons/spec-gaps":{"get":{"operationId":"VaultAssetsController_specGaps","parameters":[],"responses":{"200":{"description":"Both humanoid and quadruped are structurally verified. Remaining gaps are enforcement depth, tooling and preview assets."}},"summary":"The standard skeleton specs, and what the publish gate still lacks.","tags":["Vault"]}},"/api/v1/universal-items/inventory/me/{inventoryItemId}/spawn":{"post":{"description":"Moves the instance to `location_type = world` and records a placement every player in that world can read. Spawnable usages are `place`, `display` and `hold`. Every refusal carries a stable `code` and a sentence to show the player.","operationId":"WorldItemSpawnsController_spawn","parameters":[{"name":"inventoryItemId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpawnWorldItemRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldSpawnDto"}}}},"400":{"description":"world_not_specified · item_not_spawnable · invalid_spawn_transform"},"403":{"description":"world_suspended"},"404":{"description":"instance_not_found · world not found"},"409":{"description":"instance_not_active · item_in_use · world_spawn_cap_reached · owner_spawn_cap_reached"}},"security":[{"bearer":[]}],"summary":"Spawn one of the caller's owned instances into a world.","tags":["World Spawns"]},"delete":{"operationId":"WorldItemSpawnsController_recall","parameters":[{"name":"inventoryItemId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldRecallResponseDto"}}}},"404":{"description":"spawn_not_found"}},"security":[{"bearer":[]}],"summary":"Recall a spawned instance back to the caller's inventory.","tags":["World Spawns"]}},"/api/v1/worlds/{idOrSlug}/spawned-items":{"get":{"operationId":"WorldSpawnedItemsController_listSpawnedItems[0]","parameters":[{"name":"idOrSlug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorldSpawnDto"}}}}}}},"404":{"description":"World not found or not visible to you."}},"summary":"Every universal item currently spawned in this world.","tags":["World Spawns"]}},"/api/v1/instant-worlds/{idOrSlug}/spawned-items":{"get":{"operationId":"WorldSpawnedItemsController_listSpawnedItems[1]","parameters":[{"name":"idOrSlug","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CollectionResponseDto"}],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorldSpawnDto"}}}}}}},"404":{"description":"World not found or not visible to you."}},"summary":"Every universal item currently spawned in this world.","tags":["World Spawns"]}},"/api/v1/leaderboards/global":{"get":{"operationId":"LeaderboardsController_global","parameters":[{"name":"metric","required":false,"in":"query","schema":{"type":"string","enum":["coins_earned","lix_earned","net_worth","items_collected","trading_volume_30d","home_value","home_visits"]}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":100,"type":"number"}}],"responses":{"200":{"description":""}},"summary":"Get the cached global HELIX leaderboard.","tags":["Leaderboards"]}},"/api/v1/edit/resolve":{"get":{"description":"Read-only. Returns the workspaceKey (the Dreamer worker DO name), the fine-grained entityKind, how the workspace is hydrated, and whether a chat history exists. Returns editable:false with a machine-readable reasonCode and a human sentence when the entity has no source.","operationId":"EditController_resolve","parameters":[{"name":"kind","required":true,"in":"query","description":"Which Manage sub-tab the entity came from. Determines how it is resolved to a workspace, not what the agent is told about it — that is `entityKind` in the response.","schema":{"type":"string","enum":["world","item","asset"]}},{"name":"id","required":true,"in":"query","description":"The entity id.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Resolve an entity to its editable workspace","tags":["edit"]}},"/api/v1/edit/items/{itemId}/regenerations/{jobId}/approval-token":{"post":{"description":"Requires the creator JWT and exact Item/source/job/operation/gate. Ordinary status polling never returns this credential.","operationId":"EditController_approvalToken","parameters":[{"name":"itemId","required":true,"in":"path","schema":{"type":"string"}},{"name":"jobId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemEditApprovalTokenDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Mint a single-gate Item edit approval after a creator action","tags":["edit"]}},"/api/v1/edit/adopt":{"post":{"description":"Idempotent. Called when resolve returns needsAdoption:true. Separate from resolve on purpose — a GET that mints rows turns a page refresh into a write.","operationId":"EditController_adopt","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditAdoptDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Mint the workspace key for an entity that has none","tags":["edit"]}},"/api/v1/edit/conversations/{projectId}":{"get":{"description":"Returns the verbatim window (newest N, oldest-first), the pinned facts, and the rolling summary of everything older. Tool calls and their results are rows here, not just chat text.","operationId":"EditController_conversation","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":200,"default":20,"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Read an entity's editing history","tags":["edit"]}},"/api/v1/instant-worlds/{worldId}/source":{"post":{"description":"Opt-in: nothing calls this unless the creator asked for it. Uploading source also adopts the world into a project, which is the key its future edit-mode workspace, checkpoints and chat hang from. Only gzip tarballs are accepted.","operationId":"InstantWorldSourceController_presignUpload","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldSourceUploadRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/WorldSourceUploadTicketDto"}}}}}},"400":{"description":"Invalid content type or size."},"403":{"description":"You do not own this world."},"404":{"description":"World not found."},"409":{"description":"Legacy world that predates saved workspaces."},"503":{"description":"Source storage is not configured on this deployment. The rest of the API is unaffected — only this opt-in path is unavailable."}},"security":[{"bearer":[]}],"summary":"Presign an upload for this world's source archive.","tags":["Instant Worlds"]}},"/api/v1/instant-worlds/{worldId}/source/finalize":{"post":{"description":"Refuses unless the object exists under this project's source prefix AND its stored byte size equals the declared size — an upload that silently failed must never be recorded as an editable version.","operationId":"InstantWorldSourceController_finalize","parameters":[{"name":"worldId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldSourceFinalizeRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SingleResponseDto"}],"properties":{"item":{"$ref":"#/components/schemas/WorldSourceVersionDto"}}}}}},"400":{"description":"Upload missing, key invalid, or size mismatch."},"403":{"description":"You do not own this world."},"404":{"description":"World not found."},"409":{"description":"Legacy world that predates saved workspaces."},"503":{"description":"Source storage is not configured on this deployment."}},"security":[{"bearer":[]}],"summary":"Finalize a source upload: verify the stored bytes and record the version.","tags":["Instant Worlds"]}},"/api/v1/phone/me":{"get":{"operationId":"PhoneController_getPhone","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get current HELIX Phone account and app manifest.","tags":["Phone"]}},"/api/v1/phone/apps":{"get":{"operationId":"PhoneController_getPhoneApps","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get the HELIX Phone app manifest catalog.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}":{"get":{"operationId":"PhoneController_getPhoneApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get one HELIX Phone app manifest.","tags":["Phone"]}},"/api/v1/phone/leaderboard":{"get":{"operationId":"PhoneController_getPhoneLeaderboard","parameters":[{"name":"metric","required":false,"in":"query","schema":{"type":"string","enum":["coins_earned","lix_earned","net_worth"]}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":100,"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get HELIX Phone leaderboard app rankings.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/leaderboard":{"get":{"operationId":"PhoneController_getPhoneAppLeaderboard","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}},{"name":"metric","required":false,"in":"query","schema":{"type":"string","enum":["coins_earned","lix_earned","net_worth"]}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":100,"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get app-scoped HELIX Phone leaderboard rankings.","tags":["Phone"]}},"/api/v1/phone/permissions":{"get":{"operationId":"PhoneController_getPermissionGrants","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get effective HELIX Phone app permissions.","tags":["Phone"]}},"/api/v1/phone/permissions/audit":{"get":{"operationId":"PhoneController_getPermissionAudit","parameters":[{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get recent HELIX Phone permission audit events.","tags":["Phone"]}},"/api/v1/phone/installs":{"get":{"operationId":"PhoneController_getPhoneAppInstalls","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get installed HELIX Phone apps for this account.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/install":{"post":{"operationId":"PhoneController_installPhoneApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Install a HELIX Phone app for this account.","tags":["Phone"]},"delete":{"operationId":"PhoneController_uninstallPhoneApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"bearer":[]}],"summary":"Uninstall a HELIX Phone app for this account.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/permissions":{"put":{"operationId":"PhoneController_updateAppPermissionGrants","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePhoneAppPermissionsDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Replace granted permissions for one phone app.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/contacts":{"get":{"operationId":"PhoneController_getContactsForApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get app-scoped phone contacts.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/wallet/balance":{"get":{"operationId":"PhoneController_getWalletBalanceForApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get app-scoped read-only LIX and Coins balances.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/presence/current-world":{"get":{"operationId":"PhoneController_getCurrentWorldPresenceForApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get app-scoped current mocked world presence.","tags":["Phone"]}},"/api/v1/phone/contacts":{"get":{"operationId":"PhoneController_getContacts","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get phone contacts backed by HELIX friends.","tags":["Phone"]}},"/api/v1/phone/wallet/balance":{"get":{"operationId":"PhoneController_getWalletBalance","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get read-only LIX and Coins balances for phone apps.","tags":["Phone"]}},"/api/v1/phone/wallet/transactions":{"get":{"operationId":"PhoneController_getWalletTransactions","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List the account LIX wallet transactions, newest first, for the Wallet app \"View All Transactions\" screen.","tags":["Phone"]}},"/api/v1/phone/reports":{"post":{"operationId":"PhoneController_createReport","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePhoneReportDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"File a first-party content/abuse report from a phone app.","tags":["Phone"]},"get":{"operationId":"PhoneController_getReports","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List reports filed by this account.","tags":["Phone"]}},"/api/v1/phone/presence/current-world":{"get":{"operationId":"PhoneController_getCurrentWorldPresence","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get the current mocked world presence for phone apps.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/social/discovery/me":{"get":{"operationId":"PhoneController_getSocialDiscoveryProfile","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get the current app-scoped phone discovery profile.","tags":["Phone"]},"put":{"operationId":"PhoneController_upsertSocialDiscoveryProfile","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertPhoneSocialDiscoveryProfileDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Create or update an app-scoped phone discovery profile.","tags":["Phone"]},"delete":{"operationId":"PhoneController_deleteSocialDiscoveryProfile","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"bearer":[]}],"summary":"Disable the current app-scoped phone discovery profile.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/social/discovery":{"get":{"operationId":"PhoneController_listSocialDiscoveryProfiles","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"List app-scoped opted-in phone discovery profiles.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/social/discovery/swipes":{"post":{"operationId":"PhoneController_recordSocialDiscoverySwipe","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordPhoneSocialDiscoverySwipeDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Record a mocked app-scoped phone discovery swipe.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/iap/products":{"get":{"operationId":"PhoneController_getIapProducts","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get manifest-declared Phone IAP products.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/iap/entitlements":{"get":{"operationId":"PhoneController_getIapEntitlements","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Restore Phone IAP entitlements for an app.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/iap/purchase":{"post":{"operationId":"PhoneController_purchaseIapProduct","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchasePhoneIapDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Purchase a mocked Phone IAP product.","tags":["Phone"]}},"/api/v1/phone/notifications":{"get":{"operationId":"PhoneController_getNotifications","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get HELIX Phone notifications.","tags":["Phone"]}},"/api/v1/phone/notifications/apps/{appId}":{"get":{"operationId":"PhoneController_getNotificationsForApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get app-scoped HELIX Phone notifications.","tags":["Phone"]},"post":{"operationId":"PhoneController_createAppNotification","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePhoneNotificationDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Create a HELIX Phone app notification.","tags":["Phone"]}},"/api/v1/phone/notifications/{notificationId}/read":{"post":{"operationId":"PhoneController_markNotificationRead","parameters":[{"name":"notificationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Mark one HELIX Phone notification read.","tags":["Phone"]}},"/api/v1/phone/notifications/apps/{appId}/{notificationId}/read":{"post":{"operationId":"PhoneController_markNotificationReadForApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}},{"name":"notificationId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Mark one app-scoped HELIX Phone notification read.","tags":["Phone"]}},"/api/v1/phone/notifications/read-all":{"post":{"operationId":"PhoneController_markAllNotificationsRead","parameters":[],"responses":{"204":{"description":""}},"security":[{"bearer":[]}],"summary":"Mark all HELIX Phone notifications read.","tags":["Phone"]}},"/api/v1/phone/notifications/apps/{appId}/read":{"post":{"operationId":"PhoneController_markAppNotificationsRead","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"bearer":[]}],"summary":"Mark one app’s HELIX Phone notifications read.","tags":["Phone"]}},"/api/v1/phone/album":{"get":{"operationId":"PhoneController_getAlbum","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get the current phone album.","tags":["Phone"]}},"/api/v1/phone/album/{assetId}":{"delete":{"operationId":"PhoneController_deleteAlbumAsset","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Delete a phone album asset (purges its blob when unreferenced elsewhere).","tags":["Phone"]}},"/api/v1/phone/album/upload":{"post":{"description":"Multipart: `file` (required) plus an optional `poster` still frame for a video. Capture metadata (spatial mode, lens, zoom, filter, dimensions, duration, fps) rides on the body and is DESCRIPTIVE only — owner and world attribution always come from the session, never the body.","operationId":"PhoneController_uploadAlbumAsset","parameters":[{"name":"x-helix-world-session","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadPhoneAlbumAssetDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Upload an image or video into the phone album.","tags":["Phone"]}},"/api/v1/phone/camera/world-capture":{"post":{"description":"Multipart: `file` (required) plus an optional `poster` still for a clip. Any `worldName` on the body is IGNORED — the world title is resolved server-side from the signed session `wid`.","operationId":"PhoneController_worldCapture","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadPhoneAlbumAssetDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Save an in-engine world-camera capture to the player album.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/album":{"get":{"operationId":"PhoneController_getAlbumForApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get an app-scoped phone album view.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/album/upload":{"post":{"operationId":"PhoneController_uploadAlbumAssetForApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadPhoneAlbumAssetDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Upload app-scoped media into the phone album.","tags":["Phone"]}},"/api/v1/phone/media/{assetId}":{"get":{"operationId":"PhoneController_serveMedia","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}},{"name":"token","required":true,"in":"query","description":"Signed phone album media access token from the asset URL.","schema":{}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Serve locally-stored phone media.","tags":["Phone"]}},"/api/v1/phone/media/{assetId}/poster":{"get":{"operationId":"PhoneController_serveMediaPoster","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}},{"name":"token","required":true,"in":"query","description":"Signed phone album media access token from the asset URL.","schema":{}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Serve a locally-stored capture poster frame.","tags":["Phone"]}},"/api/v1/phone/messages/threads":{"get":{"description":"Without `since`, returns every thread carrying only its 50 most recent messages. With `since=<cursor>`, returns ONLY messages newer than the cursor across all threads (the reconnect/visibility backfill), flagged with `delta: true` and capped with `hasMore`.","operationId":"PhoneController_getMessageThreads","parameters":[{"name":"since","required":true,"in":"query","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get HELIX Phone message threads.","tags":["Phone"]}},"/api/v1/phone/messages/realtime":{"get":{"description":"A few bytes, deliberately. While the fallback poll is stood down, a client re-asks this on a slow cadence so that an IDLE RECIPIENT — one who never sends, and so never triggers the send-echo watchdog — cannot be stranded by a push path that broke mid-session. It is NOT a second poll: it returns one boolean and never a thread, so \"zero /threads requests while idle\" keeps meaning exactly what it says. Do not \"simplify\" it by folding it back into GET messages/threads.","operationId":"PhoneController_getMessagesRealtime","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Is the realtime MESSAGE channel actually carrying?","tags":["Phone"]}},"/api/v1/phone/realtime":{"get":{"description":"The same question as GET messages/realtime, for every channel that rides the shared presence stream: messages, calls and notifications (CH-852). Each is answered from a real authenticated round-trip over the exact worker route THAT channel pushes through, so a worker deploy that predates one of the routes answers false for it and true for the others. Absent or false means POLL. A client that stands a poll down on anything less than a true here is repeating the 2026-07-21 outage.","operationId":"PhoneController_getRealtimeChannels","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Which realtime channels are actually carrying?","tags":["Phone"]}},"/api/v1/phone/messages/threads/{threadId}/messages":{"get":{"description":"Walks backwards from `before=<cursor>` (omit for the newest page). Keyset, never OFFSET — OFFSET drifts when messages arrive mid-scroll, which in a chat thread means duplicated or skipped rows.","operationId":"PhoneController_getThreadMessages","parameters":[{"name":"threadId","required":true,"in":"path","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get one thread’s history, keyset-paginated.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/messages/threads":{"get":{"operationId":"PhoneController_getMessageThreadsForApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get app-scoped HELIX Phone message threads.","tags":["Phone"]}},"/api/v1/phone/messages":{"post":{"description":"Idempotent on `clientId`: a retried send returns the ORIGINAL message rather than delivering twice. `item` is the sender’s thread (unchanged shape, for clients that predate this release); `message` is the single message the optimistic bubble reconciles against.","operationId":"PhoneController_sendMessage","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendPhoneMessageDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Send a HELIX Phone message.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/messages":{"post":{"operationId":"PhoneController_sendMessageForApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendPhoneMessageDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Send an app-scoped HELIX Phone message.","tags":["Phone"]}},"/api/v1/phone/messages/{pairId}/reaction":{"put":{"description":"Keyed on `pairId`, the identity shared by both mirrored copies of a message — so ONE row serves both participants. One tapback per person per message: sending a different one replaces yours, and you can never touch anyone else’s. Authorized by owning a thread that contains the pair, so a pairId from a conversation you are not in simply 404s.","operationId":"PhoneController_setMessageReaction","parameters":[{"name":"pairId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReactToPhoneMessageDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Set (or replace) your tapback on a message.","tags":["Phone"]},"delete":{"description":"Scoped to the caller: the delete predicate includes `user_id`, so there is no id a client could send that would remove someone else’s reaction.","operationId":"PhoneController_removeMessageReaction","parameters":[{"name":"pairId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Remove your own tapback from a message.","tags":["Phone"]}},"/api/v1/phone/messages/threads/{threadId}/read":{"post":{"operationId":"PhoneController_markMessageThreadRead","parameters":[{"name":"threadId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Mark a HELIX Phone message thread read.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/messages/threads/{threadId}/read":{"post":{"operationId":"PhoneController_markMessageThreadReadForApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}},{"name":"threadId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Mark an app-scoped HELIX Phone message thread read.","tags":["Phone"]}},"/api/v1/phone/calls":{"get":{"operationId":"PhoneController_getCallLogs","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get HELIX Phone call logs.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/calls":{"get":{"operationId":"PhoneController_getCallLogsForApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get app-scoped HELIX Phone call logs.","tags":["Phone"]}},"/api/v1/phone/calls/mock":{"post":{"operationId":"PhoneController_placeMockCall","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacePhoneCallDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Place a HELIX voice call to a contact.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/calls/mock":{"post":{"operationId":"PhoneController_placeMockCallForApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacePhoneCallDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Place an app-scoped HELIX voice call to a contact.","tags":["Phone"]}},"/api/v1/phone/calls/mock/incoming":{"post":{"operationId":"PhoneController_simulateIncomingMockCall","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacePhoneCallDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Simulate an incoming HELIX voice call.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/calls/mock/incoming":{"post":{"operationId":"PhoneController_simulateIncomingMockCallForApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacePhoneCallDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Simulate an app-scoped incoming HELIX voice call.","tags":["Phone"]}},"/api/v1/phone/calls/{callId}/status":{"post":{"operationId":"PhoneController_updateMockCallStatus","parameters":[{"name":"callId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePhoneCallStatusDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Answer, decline or end a HELIX voice call.","tags":["Phone"]}},"/api/v1/phone/calls/{callId}/voice-token":{"post":{"operationId":"PhoneController_createCallVoiceToken","parameters":[{"name":"callId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Mint the LiveKit grant for this call — the media half of a HELIX Phone call.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/calls/{callId}/status":{"post":{"operationId":"PhoneController_updateMockCallStatusForApp","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}},{"name":"callId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePhoneCallStatusDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Answer, decline or end an app-scoped HELIX voice call.","tags":["Phone"]}},"/api/v1/phone/apps/{appId}/storage/{key}":{"get":{"operationId":"PhoneController_getAppStorage","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}},{"name":"key","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Read app-scoped HELIX Phone storage.","tags":["Phone"]},"put":{"operationId":"PhoneController_setAppStorage","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}},{"name":"key","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertPhoneAppStorageDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Write app-scoped HELIX Phone storage.","tags":["Phone"]},"delete":{"operationId":"PhoneController_deleteAppStorage","parameters":[{"name":"appId","required":true,"in":"path","schema":{"type":"string"}},{"name":"key","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"bearer":[]}],"summary":"Delete app-scoped HELIX Phone storage.","tags":["Phone"]}},"/api/v1/phone/admin/media/{assetId}/takedown":{"post":{"operationId":"PhoneMediaReviewController_takedown","parameters":[{"name":"assetId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TakeDownPhoneMediaDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Take down a phone album asset from ANY state — deletes its bytes.","tags":["Phone"]}},"/api/v1/moderation/reports":{"post":{"operationId":"ModerationController_createReport","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateModerationReportDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Submit a universal moderation report.","tags":["Moderation"]}},"/api/v1/moderation/reports/evidence-uploads":{"post":{"operationId":"ModerationController_mintEvidenceUploads","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportEvidenceUploadRequestDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Mint presigned upload slots for report evidence (HYPR-5216). PUT each file to its uploadUrl, then submit the report with each storageKey on its evidence entry.","tags":["Moderation"]}},"/api/v1/moderation/admin/reports/{reportId}/evidence/{evidenceIndex}/download":{"get":{"operationId":"ModerationController_downloadEvidence","parameters":[{"name":"reportId","required":true,"in":"path","schema":{"type":"string"}},{"name":"evidenceIndex","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Short-lived signed URL for one uploaded evidence attachment — the same posture as quarantine review (no public serve route).","tags":["Moderation"]}},"/api/v1/moderation/admin/overview":{"get":{"operationId":"ModerationController_getOverview","parameters":[{"name":"range","required":false,"in":"query","description":"Rolling window for trend, throughput, and \"new in range\".","schema":{"default":"30d","type":"string","enum":["7d","30d","90d"]}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Unified platform-health overview: user counts, report volume/trend, moderation throughput, and trust-band distribution.","tags":["Moderation"]}},"/api/v1/moderation/admin/users":{"get":{"operationId":"ModerationController_listAdminUsers","parameters":[{"name":"search","required":false,"in":"query","description":"Free-text lookup by username, display name, or email. When set, matches across all users; otherwise the roster is the moderation-signal population.","schema":{"type":"string"}},{"name":"band","required":false,"in":"query","schema":{"type":"string","enum":["trusted","watch","limited","restricted"]}},{"name":"sort","required":false,"in":"query","schema":{"default":"trust_asc","type":"string","enum":["trust_asc","trust_desc","flags","recent"]}},{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":100,"default":25,"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Users/Trust roster: moderation-signal users (or a search across all users) with trust score, band, and flag counts.","tags":["Moderation"]}},"/api/v1/moderation/admin/reports":{"get":{"operationId":"ModerationController_listReports","parameters":[{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["open","reviewing","resolved","dismissed","actioned"]}},{"name":"queue","required":false,"in":"query","description":"When true, return only rows awaiting a human: every user-filed report plus AI rating disagreements, excluding the automated scan audit trail (automated_glb/automated_image), which passes and is never closed. This is the moderation QUEUE — see report-queue.ts.","schema":{"type":"boolean"}},{"name":"targetType","required":false,"in":"query","schema":{"type":"string","enum":["user","world","home","universal_item","canvas_item","collectible","collectible_instance","helixgram_post","helixgram_comment","helixgram_story","h_post","phone_post","phone_comment","phone_story","other"]}},{"name":"targetId","required":false,"in":"query","schema":{"type":"string"}},{"name":"reportedUserId","required":false,"in":"query","schema":{"type":"string"}},{"name":"reporterId","required":false,"in":"query","schema":{"type":"string"}},{"name":"reporter","required":false,"in":"query","description":"Reporter lookup by UUID, username, display name, or email.","schema":{"type":"string"}},{"name":"reportedUser","required":false,"in":"query","description":"Reported user lookup by UUID, username, display name, or email.","schema":{"type":"string"}},{"name":"type","required":false,"in":"query","description":"Report type/reason filter.","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":100,"default":25,"type":"number"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] List moderation reports with filters.","tags":["Moderation"]}},"/api/v1/moderation/admin/reports/{reportId}":{"patch":{"operationId":"ModerationController_updateReport","parameters":[{"name":"reportId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateModerationReportDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Review or action a moderation report.","tags":["Moderation"]}},"/api/v1/moderation/admin/content-rating":{"post":{"operationId":"ModerationController_updateContentRating","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContentRatingDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Update content rating workflow state for a target.","tags":["Moderation"]}},"/api/v1/moderation/admin/repeat-offenders":{"get":{"operationId":"ModerationController_listRepeatOffenders","parameters":[{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] List repeat reported users.","tags":["Moderation"]}},"/api/v1/moderation/admin/trust-score/{userId}":{"get":{"operationId":"ModerationController_getTrustScore","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Read private trust score V1 for a user.","tags":["Moderation"]}},"/api/v1/moderation/admin/users/{userId}":{"get":{"operationId":"ModerationController_getUserModerationProfile","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"historyLimit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] User moderation view: trust score, escalation, flag counts, repeat-offender status, and full moderation history (automated + manual).","tags":["Moderation"]}},"/api/v1/moderation/admin/reports/{reportId}/restore":{"post":{"operationId":"ModerationController_restoreTakedown","parameters":[{"name":"reportId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Reverse a takedown applied from this report, restoring the content to the status it held beforehand. Required for worlds, which have no other admin path out of Suspended.","tags":["Moderation"]}},"/api/v1/moderation/admin/users/{userId}/creation-suspension":{"get":{"operationId":"ModerationController_getCreationStanding","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Read an account's creation-suspension standing.","tags":["Moderation"]},"post":{"operationId":"ModerationController_suspendCreation","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuspendCreationDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Pause publishing/creating for an account. Login, browsing, and purchases are unaffected.","tags":["Moderation"]}},"/api/v1/moderation/admin/users/{userId}/creation-suspension/lift":{"post":{"operationId":"ModerationController_liftCreationSuspension","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsuspendCreationDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Restore publishing for a creation-suspended account.","tags":["Moderation"]}},"/api/v1/moderation/admin/policy":{"get":{"operationId":"ModerationPolicyController_getPolicy","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"The active moderation posture: every surface, its resolved mode, and why.","tags":["Moderation"]},"put":{"operationId":"ModerationPolicyController_updatePolicy","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateModerationPolicyDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Publish a new moderation posture.","tags":["Moderation"]}},"/api/v1/moderation/admin/policy/history":{"get":{"operationId":"ModerationPolicyController_getHistory","parameters":[{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"The moderation posture version log, newest first.","tags":["Moderation"]}},"/api/v1/moderation/admin/policy/revert":{"post":{"operationId":"ModerationPolicyController_revertPolicy","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevertModerationPolicyDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Re-publish the previous posture as a new version.","tags":["Moderation"]}},"/api/v1/moderation/admin/quarantine":{"get":{"operationId":"QuarantineController_list","parameters":[{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"offset","required":true,"in":"query","schema":{"type":"string"}},{"name":"decision","required":true,"in":"query","schema":{"type":"string"}},{"name":"csam","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] List quarantined rejected/held media (metadata only). CSAM rows hidden unless csam=true.","tags":["Moderation"]}},"/api/v1/moderation/admin/quarantine/{id}":{"get":{"operationId":"QuarantineController_getOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get a single quarantine record (metadata).","tags":["Moderation"]}},"/api/v1/moderation/admin/quarantine/{id}/content":{"get":{"operationId":"QuarantineController_getContent","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Mint a short-lived signed URL to review the quarantined bytes. 403 for CSAM-flagged records.","tags":["Moderation"]}},"/api/v1/moderation/admin/quarantine/{id}/override":{"post":{"operationId":"QuarantineController_override","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateModerationOverrideDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Record a human override of an automated REJECT, so re-uploading this exact file succeeds. Requires a written reason. 403 for CSAM-flagged records; 400 for holds and for rejects that were never actually inspected.","tags":["Moderation"]}},"/api/v1/moderation/admin/quarantine/{id}/purge":{"post":{"operationId":"QuarantineController_purge","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Immediately purge a quarantined object (deletes the bytes, keeps the record). 403 for CSAM-flagged records (legal hold).","tags":["Moderation"]}},"/api/v1/moderation/admin/overrides":{"get":{"operationId":"ModerationOverrideController_list","parameters":[{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"offset","required":true,"in":"query","schema":{"type":"string"}},{"name":"state","required":true,"in":"query","schema":{"type":"string"}},{"name":"sha256","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] List recorded moderation overrides (who allowed which asset, when, why, and how many times it has been honoured).","tags":["Moderation"]}},"/api/v1/moderation/admin/overrides/{id}":{"get":{"operationId":"ModerationOverrideController_getOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Get one override record.","tags":["Moderation"]}},"/api/v1/moderation/admin/overrides/{id}/revoke":{"post":{"operationId":"ModerationOverrideController_revoke","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeModerationOverrideDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Revoke an override. Re-uploads of those bytes reject again. The record is retained — revocation is part of the audit history, not a delete.","tags":["Moderation"]}},"/api/v1/h/feed":{"get":{"operationId":"HController_getFeed","parameters":[{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get the public H feed.","tags":["H"]}},"/api/v1/h/feed/me":{"get":{"operationId":"HController_getAuthenticatedFeed","parameters":[{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}},{"name":"scope","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get the authenticated H feed.","tags":["H"]}},"/api/v1/h/trends":{"get":{"operationId":"HController_getTrends","parameters":[{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get trending H hashtags.","tags":["H"]}},"/api/v1/h/search":{"get":{"operationId":"HController_search","parameters":[{"name":"q","required":true,"in":"query","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Search H posts and users.","tags":["H"]}},"/api/v1/h/users/{userId}/posts":{"get":{"operationId":"HController_getUserPosts","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get H posts for a profile.","tags":["H"]}},"/api/v1/h/users/{userId}/posts/me":{"get":{"operationId":"HController_getAuthenticatedUserPosts","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get H posts for a profile as this viewer.","tags":["H"]}},"/api/v1/h/users/{userId}/social/me":{"get":{"operationId":"HController_getAuthenticatedSocial","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get H follow counts for this viewer.","tags":["H"]}},"/api/v1/h/posts/{postId}/replies":{"get":{"operationId":"HController_getReplies","parameters":[{"name":"postId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":true,"in":"query","schema":{"type":"string"}},{"name":"before","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Get replies for an H post.","tags":["H"]},"post":{"operationId":"HController_replyToPost","parameters":[{"name":"postId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHReplyDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Reply to an H post.","tags":["H"]}},"/api/v1/h/posts":{"post":{"operationId":"HController_createPost","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHPostDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Create an H post.","tags":["H"]}},"/api/v1/h/posts/{postId}":{"delete":{"operationId":"HController_deletePost","parameters":[{"name":"postId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Delete your own H post.","tags":["H"]}},"/api/v1/h/posts/{postId}/repost":{"post":{"operationId":"HController_repost","parameters":[{"name":"postId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Repost an H post.","tags":["H"]}},"/api/v1/h/posts/{postId}/like":{"post":{"operationId":"HController_likePost","parameters":[{"name":"postId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Like an H post.","tags":["H"]},"delete":{"operationId":"HController_unlikePost","parameters":[{"name":"postId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Unlike an H post.","tags":["H"]}},"/api/v1/h/users/{userId}/follow":{"post":{"operationId":"HController_followUser","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Follow an H user.","tags":["H"]},"delete":{"operationId":"HController_unfollowUser","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Unfollow an H user.","tags":["H"]}},"/api/v1/h/reports":{"post":{"operationId":"HController_reportContent","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHReportDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Report H content for moderation.","tags":["H"]}},"/api/v1/creator/analytics/summary":{"get":{"operationId":"CreatorAnalyticsController_getSummary","parameters":[{"name":"range","required":false,"in":"query","description":"7d | 28d | 90d | 12m. Default 28d. Ignored when from/to are sent.","schema":{"example":"28d","type":"string"}},{"name":"from","required":false,"in":"query","description":"Explicit window start. Must be sent WITH `to`.","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"Explicit window end. Must be sent WITH `from`.","schema":{"type":"string"}},{"name":"compare","required":false,"in":"query","schema":{"default":"previous","type":"string","enum":["previous","none"]}},{"name":"scope","required":false,"in":"query","schema":{"default":"all","type":"string","enum":["all","world","item"]}},{"name":"cohortScope","required":false,"in":"query","description":"Identity population used for uniques, returning actors and retention. Anonymous cohorts are available but less stable when browser storage is cleared.","schema":{"default":"signed_in","type":"string","enum":["signed_in","all"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorAnalyticsSummaryResponseDto"}}}},"400":{"description":"{ code: \"range_too_large\", maxDays: 90 } — never a silently truncated window."},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Portfolio earnings for the caller: gross (union of the money ledgers), comparison, trend, breakdown and top buyers.","tags":["Creator analytics"]}},"/api/v1/creator/analytics/subjects":{"get":{"operationId":"CreatorAnalyticsController_getSubjects","parameters":[{"name":"range","required":false,"in":"query","description":"7d | 28d | 90d | 12m. Default 28d. Ignored when from/to are sent.","schema":{"example":"28d","type":"string"}},{"name":"from","required":false,"in":"query","description":"Explicit window start. Must be sent WITH `to`.","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"Explicit window end. Must be sent WITH `from`.","schema":{"type":"string"}},{"name":"compare","required":false,"in":"query","schema":{"default":"previous","type":"string","enum":["previous","none"]}},{"name":"scope","required":false,"in":"query","schema":{"default":"all","type":"string","enum":["all","world","item"]}},{"name":"cohortScope","required":false,"in":"query","description":"Identity population used for uniques, returning actors and retention. Anonymous cohorts are available but less stable when browser storage is cleared.","schema":{"default":"signed_in","type":"string","enum":["signed_in","all"]}},{"name":"type","required":false,"in":"query","schema":{"default":"item","type":"string","enum":["item","world","product"]}},{"name":"sort","required":false,"in":"query","schema":{"default":"gross","type":"string","enum":["gross","units","views","conversion"]}},{"name":"cursor","required":false,"in":"query","description":"Keyset cursor from a previous page.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"maximum":100,"default":50,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorAnalyticsSubjectsResponseDto"}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Per-subject aggregates over the range with a sparkline per row. This is the endpoint the Manage grid needs to put stats on item cards.","tags":["Creator analytics"]}},"/api/v1/creator/analytics/checklist":{"get":{"operationId":"CreatorAnalyticsController_getChecklist","parameters":[{"name":"type","required":false,"in":"query","schema":{"default":"item","type":"string","enum":["item"]}},{"name":"limit","required":false,"in":"query","schema":{"maximum":100,"default":50,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorAnalyticsChecklistResponseDto"}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Tier-0 per-item action codes. No range and no sales/view dependency.","tags":["Creator analytics"]}},"/api/v1/creator/analytics/subject/{type}/{id}":{"get":{"operationId":"CreatorAnalyticsController_getSubject","parameters":[{"name":"type","required":true,"in":"path","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"range","required":false,"in":"query","description":"7d | 28d | 90d | 12m. Default 28d. Ignored when from/to are sent.","schema":{"example":"28d","type":"string"}},{"name":"from","required":false,"in":"query","description":"Explicit window start. Must be sent WITH `to`.","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"Explicit window end. Must be sent WITH `from`.","schema":{"type":"string"}},{"name":"compare","required":false,"in":"query","schema":{"default":"previous","type":"string","enum":["previous","none"]}},{"name":"scope","required":false,"in":"query","schema":{"default":"all","type":"string","enum":["all","world","item"]}},{"name":"cohortScope","required":false,"in":"query","description":"Identity population used for uniques, returning actors and retention. Anonymous cohorts are available but less stable when browser storage is cleared.","schema":{"default":"signed_in","type":"string","enum":["signed_in","all"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorAnalyticsSubjectResponseDto"}}}},"401":{"description":"Unauthorized."},"404":{"description":"Not found, or not owned by the caller — deliberately indistinguishable, so the route does not enumerate other creators’ subjects."}},"security":[{"bearer":[]}],"summary":"One subject, same payload shape as /summary plus soldWhere — so the item panel and the world panel are the same component.","tags":["Creator analytics"]}},"/api/v1/creator/analytics/customers/{id}":{"get":{"operationId":"CreatorAnalyticsController_getCustomer","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"range","required":false,"in":"query","description":"7d | 28d | 90d | 12m. Default 28d. Ignored when from/to are sent.","schema":{"example":"28d","type":"string"}},{"name":"from","required":false,"in":"query","description":"Explicit window start. Must be sent WITH `to`.","schema":{"type":"string"}},{"name":"to","required":false,"in":"query","description":"Explicit window end. Must be sent WITH `from`.","schema":{"type":"string"}},{"name":"compare","required":false,"in":"query","schema":{"default":"previous","type":"string","enum":["previous","none"]}},{"name":"scope","required":false,"in":"query","schema":{"default":"all","type":"string","enum":["all","world","item"]}},{"name":"cohortScope","required":false,"in":"query","description":"Identity population used for uniques, returning actors and retention. Anonymous cohorts are available but less stable when browser storage is cleared.","schema":{"default":"signed_in","type":"string","enum":["signed_in","all"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorAnalyticsCustomerResponseDto"}}}},"401":{"description":"Unauthorized."},"404":{"description":"Not found, or no purchase of this creator’s work — deliberately indistinguishable."}},"security":[{"bearer":[]}],"summary":"Creator-private customer summary, restricted to purchases of the caller’s own worlds and items.","tags":["Creator analytics"]}},"/api/v1/ftue/me":{"get":{"operationId":"FtueController_getMine","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FtueStateResponseDto"}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Get the authenticated user FTUE mission state.","tags":["FTUE"]}},"/api/v1/ftue/start":{"post":{"operationId":"FtueController_start","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartFtueRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FtueStateResponseDto"}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Start or update the FTUE entry handoff.","tags":["FTUE"]}},"/api/v1/ftue/entry/username-confirmed":{"post":{"operationId":"FtueController_confirmUsername","parameters":[],"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FtueStateResponseDto"}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Record that the player completed the entry-flow username screen. Call it AFTER the username itself is saved (PATCH /api/v1/users/me).","tags":["FTUE"]}},"/api/v1/ftue/interests":{"patch":{"operationId":"FtueController_updateInterests","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFtueInterestsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FtueStateResponseDto"}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Update FTUE interest routing hints.","tags":["FTUE"]}},"/api/v1/ftue/avatar":{"patch":{"operationId":"FtueController_updateAvatar","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFtueAvatarRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FtueStateResponseDto"}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Record the entry-flow avatar choice.","tags":["FTUE"]}},"/api/v1/ftue/hud/dismiss":{"post":{"operationId":"FtueController_dismissHud","parameters":[],"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FtueStateResponseDto"}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Hide the onboarding quest HUD for this account, permanently. Idempotent; no milestone requirement.","tags":["FTUE"]}},"/api/v1/ftue/steps/{stepId}/complete":{"post":{"operationId":"FtueController_completeStep","parameters":[{"name":"stepId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteFtueStepRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FtueStateResponseDto"}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Complete one FTUE quest step.","tags":["FTUE"]}},"/api/v1/ftue/rewards/starter/claim":{"post":{"operationId":"FtueController_claimStarterBundle","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimStarterRewardsRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FtueStateResponseDto"}}}},"401":{"description":"Unauthorized."}},"security":[{"bearer":[]}],"summary":"Claim the idempotent starter FTUE bundle.","tags":["FTUE"]}},"/api/v1/helixpedia/articles":{"get":{"operationId":"HelixpediaController_list","parameters":[],"responses":{"200":{"description":"The full curated article corpus."}},"summary":"List all Helixpedia articles.","tags":["Helixpedia"]}},"/api/v1/helixpedia/search":{"get":{"operationId":"HelixpediaController_search","parameters":[{"name":"q","required":true,"in":"query","description":"Search query.","schema":{"type":"string"}}],"responses":{"200":{"description":"Ranked search hits."}},"summary":"Search Helixpedia by title, category, and lead text.","tags":["Helixpedia"]}},"/api/v1/helixpedia/articles/{slug}":{"get":{"operationId":"HelixpediaController_get","parameters":[{"name":"slug","required":true,"in":"path","description":"Stable article slug / wikilink target.","schema":{"type":"string"}}],"responses":{"200":{"description":"The article record."}},"summary":"Get a single Helixpedia article by slug.","tags":["Helixpedia"]}},"/api/v1/qa/test-accounts":{"post":{"operationId":"QaTestAccountsController_provision","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionTestAccountsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionTestAccountsResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[DEV/HELIX3 ADMIN] Ensure stable passwordless QA accounts.","tags":["QA / Test Accounts"]}},"/api/v1/qa/test-accounts/{id}/session":{"post":{"operationId":"QaTestAccountsController_mintSession","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponseDto"}}}}},"security":[{"bearer":[]}],"summary":"[DEV/HELIX3 ADMIN] Mint the normal web-shell login token shape for a QA fixture.","tags":["QA / Test Accounts"]}},"/api/v1/admin/mission-control/events":{"get":{"operationId":"MissionControlController_list","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Query sanitized operational incidents.","tags":["Mission Control"]}},"/api/v1/admin/mission-control/events/{eventId}/actions":{"get":{"operationId":"MissionControlController_actionHistory","parameters":[{"name":"eventId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"tags":["Mission Control"]}},"/api/v1/admin/mission-control/events/{eventId}":{"patch":{"operationId":"MissionControlController_act","parameters":[{"name":"eventId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MissionControlActionDto"}}}},"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Acknowledge or resolve an incident.","tags":["Mission Control"]}},"/api/v1/admin/mission-control/stream":{"get":{"operationId":"MissionControlController_stream","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"[ADMIN] Live sanitized incident-change stream.","tags":["Mission Control"]}}},"info":{"title":"HELIX Backend API","description":"API for interacting with HELIX backend services.","version":"1.0","contact":{}},"tags":[],"servers":[],"components":{"securitySchemes":{"client_credentials":{"type":"http","scheme":"basic","description":"Use clientId:clientSecret as Basic Auth credentials"},"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"User JWT token for authentication"},"oauth_access":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"OAuth2.0 access token for applications performing actions on behalf of user"},"shared_secret":{"type":"apiKey","in":"header","name":"Authorization","description":"Shared secret authentication using format: SharedSecret <secret>"}},"schemas":{"ListResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Token id","example":"123abc"},"nickname":{"type":"string","description":"Token nickname.","example":"My client token"},"description":{"type":"object","description":"Token description.","example":"Token for auto-deployments","nullable":true},"expiresAt":{"type":"number","description":"Token expiration timestamp (seconds)","example":1234567890},"createdAt":{"type":"number","description":"Token creation timestamp (seconds)","example":1234567890}},"required":["id","nickname","description","expiresAt","createdAt"]},"GenerateRequestDto":{"type":"object","properties":{"nickname":{"type":"string","description":"Token nickname.","example":"My client token"},"description":{"type":"object","description":"Token description.","example":"Token for auto-deployments","nullable":true},"expiresAt":{"type":"number","description":"Token expiration timestamp (seconds)","example":1234567890}},"required":["nickname","expiresAt"]},"GenerateResponseDto":{"type":"object","properties":{"clientToken":{"type":"string","description":"Client token.","example":"123abc"},"tokenType":{"type":"string","description":"Token type, typically \"Bearer\".","example":"Bearer"},"nickname":{"type":"string","description":"Token nickname.","example":"My client token"},"description":{"type":"object","description":"Token description.","example":"Token for auto-deployments","nullable":true},"expiresAt":{"type":"number","description":"Token expiration timestamp (seconds)","example":1234567890}},"required":["clientToken","tokenType","nickname","description","expiresAt"]},"PaginationResponseDto":{"type":"object","properties":{"current":{"type":"number","description":"The current page number.","example":1},"total":{"type":"number","description":"The total number of pages.","example":5},"size":{"type":"number","description":"The number of items per page.","example":20}},"required":["current","total","size"]},"PageInfoResponseDto":{"type":"object","properties":{"nextCursor":{"type":"object","description":"Opaque cursor for the next page (pass back as `?cursor=`). Null on the last page.","nullable":true,"example":"MjAyNi0wNy0xNVQxMDoxMTowMC4wMDBafGRlYWRiZWVm"},"hasNextPage":{"type":"boolean","description":"Whether a further page exists after this one.","example":true}},"required":["nextCursor","hasNextPage"]},"CollectionResponseDto":{"type":"object","properties":{"items":{"description":"The items in the collection.","type":"array","items":{"type":"object"}},"totalItems":{"type":"number","description":"The total number of items in the collection.","example":100},"pagination":{"description":"The pagination information.","allOf":[{"$ref":"#/components/schemas/PaginationResponseDto"}]},"pageInfo":{"description":"Keyset/cursor pagination info for infinite scroll.","allOf":[{"$ref":"#/components/schemas/PageInfoResponseDto"}]}},"required":["items","totalItems","pagination"]},"UserResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the user.","example":"123e4567-e89b-12d3-a456-426614174000"},"username":{"type":"string","description":"The username of the user.","example":"exampleuser1"},"displayName":{"type":"object","description":"The display name of the user.","example":"Conqr","nullable":true},"bio":{"type":"object","description":"User's custom bio.","example":"My name is Conqr and I like ducks.","nullable":true},"avatarUrl":{"type":"object","description":"The URL to the user's avatar.","example":"https://users.helix-cdn.com/123e4567-e89b-12d3-a456-426614174000/avatar","nullable":true},"bannerUrl":{"type":"object","description":"The URL to the user's banner.","example":"https://users.helix-cdn.com/123e4567-e89b-12d3-a456-426614174000/banner","nullable":true},"subscriptionTier":{"type":"string","description":"The public subscription tier used for profile benefits.","enum":["free","plus","gold","diamond"],"default":"free"},"country":{"type":"object","description":"User's country (self selected).","example":"US","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"The date the user was created.","example":"2025-07-08T12:34:56.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"The date the user was last updated.","example":"2025-07-08T12:34:56.000Z"},"friend":{"type":"boolean","description":"Whether the authenticated user is friends with this user.","example":true},"blocked":{"type":"boolean","description":"Whether the authenticated user has blocked this user.","example":false},"presence":{"type":"object","description":"Presence visible to the authenticated viewer after online status privacy is applied.","nullable":true}},"required":["id","username","displayName","bio","avatarUrl","bannerUrl","subscriptionTier","country","createdAt","updatedAt"]},"SingleResponseDto":{"type":"object","properties":{"item":{"type":"object","description":"The item returned in the response."}},"required":["item"]},"FriendRequestResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the friend request."},"requesterId":{"type":"string","description":"The ID of the user who sent the request."},"recipientId":{"type":"string","description":"The ID of the user who received the request."},"status":{"type":"string","enum":["pending","accepted","rejected"],"description":"The status of the friend request."},"createdAt":{"format":"date-time","type":"string","description":"The date the request was created."}},"required":["id","requesterId","recipientId","status","createdAt"]},"UpdatePresenceRequestDto":{"type":"object","properties":{"status":{"type":"string","enum":["online","away","offline"]},"worldId":{"type":"string","description":"Current Instant World id."},"worldSlug":{"type":"string","description":"Current Instant World slug."},"instanceId":{"type":"string","description":"Current World or Home room id."},"homeId":{"type":"string","description":"Current or preferred home id."},"homeSlug":{"type":"string","description":"Current or preferred home slug."},"label":{"type":"string","description":"Short user-facing presence label."}}},"PresenceActivityPartyDto":{"type":"object","properties":{"current":{"type":"number","description":"Current party size.","example":2},"max":{"type":"number","description":"Max party size.","example":8}},"required":["current","max"]},"SetPresenceActivityRequestDto":{"type":"object","properties":{"state":{"type":"string","description":"Free-form activity line shown to permitted viewers, e.g. \"Racing — lap 3/5\".","example":"Racing — lap 3/5","maxLength":128},"details":{"type":"string","description":"Secondary activity detail line.","maxLength":128},"image":{"type":"string","description":"Custom activity image (asset key or URL). Omit to default to the world thumbnail.","maxLength":300},"party":{"$ref":"#/components/schemas/PresenceActivityPartyDto"},"joinable":{"type":"boolean","description":"Hint that this activity is joinable (gated by MP runtime).","default":false},"worldId":{"type":"string","description":"World the activity is for. Must equal the caller current presence world."}},"required":["state"]},"ReportUserRequestDto":{"type":"object","properties":{"reason":{"type":"string","description":"Short moderation reason.","example":"harassment"},"details":{"type":"string","description":"Optional details for moderators.","maxLength":2000},"metadata":{"type":"object","description":"Optional client context such as route, instance, or message id."}},"required":["reason"]},"WalletResponseDto":{"type":"object","properties":{"wallet_id":{"type":"string","description":"The unique identifier of the wallet.","example":"wallet_123456789"},"user_id":{"type":"string","description":"The unique identifier of the user who owns the wallet.","example":"user_987654321"},"wallet_type":{"type":"string","description":"The type of the wallet.","example":"user"},"system_wallet_name":{"type":"string","description":"The name of the system wallet (if applicable).","example":"marketplace_commission"},"withdrawable_balance":{"type":"number","description":"The withdrawable balance of the wallet.","example":100.5},"non_withdrawable_balance":{"type":"number","description":"The non-withdrawable balance of the wallet.","example":25.75},"pending_withdrawable_balance":{"type":"number","description":"The pending withdrawable balance of the wallet (funds that will become withdrawable after maturity period).","example":50},"currency":{"type":"string","description":"The currency of the wallet.","example":"USD"},"status":{"type":"string","description":"The status of the wallet.","example":"active"},"version":{"type":"number","description":"The version of the wallet for optimistic locking.","example":1},"created_at":{"type":"string","description":"The creation timestamp of the wallet.","example":"2024-01-15T10:30:00Z"},"updated_at":{"type":"string","description":"The last update timestamp of the wallet.","example":"2024-01-15T15:45:00Z"}},"required":["wallet_id","wallet_type","withdrawable_balance","non_withdrawable_balance","pending_withdrawable_balance","currency","status","version","created_at","updated_at"]},"UserAdminResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the user.","example":"123e4567-e89b-12d3-a456-426614174000"},"username":{"type":"string","description":"The username of the user.","example":"exampleuser1"},"displayName":{"type":"object","description":"The display name of the user.","example":"Conqr","nullable":true},"isAdmin":{"type":"boolean","description":"Whether the user is an admin.","example":true},"bio":{"type":"object","description":"User's custom bio.","example":"My name is Conqr and I like ducks.","nullable":true},"avatarUrl":{"type":"object","description":"The URL to the user's avatar.","example":"https://users.helix-cdn.com/123e4567-e89b-12d3-a456-426614174000/avatar","nullable":true},"bannerUrl":{"type":"object","description":"The URL to the user's banner.","example":"https://users.helix-cdn.com/123e4567-e89b-12d3-a456-426614174000/banner","nullable":true},"country":{"type":"object","description":"User's country (self selected).","example":"US","nullable":true},"email":{"type":"string","description":"The email of the user.","example":"user@example.com"},"verifiedAt":{"type":"object","description":"The date when the user verified their email.","example":"2024-01-15T10:30:00Z","nullable":true},"isActive":{"type":"boolean","description":"Whether the user account is active.","example":true},"canCreateCollectibles":{"type":"boolean","description":"Whether the user can create collectibles.","example":false},"actionToken":{"type":"object","description":"Action token for user account actions.","example":null,"nullable":true},"ipHash":{"type":"object","description":"Hash of user IP address.","example":"5f4dcc3b5aa765d61d8327deb882cf99","nullable":true},"referredByUserId":{"type":"object","description":"ID of the user who referred this user via invite code.","example":"123e4567-e89b-12d3-a456-426614174000","nullable":true},"inviteCodesQuota":{"type":"number","description":"Number of invite codes this user can generate.","example":5},"allowedToGenerateInviteCode":{"type":"boolean","description":"Whether the user is allowed to generate invite codes.","example":true},"createdAt":{"format":"date-time","type":"string","description":"The date the user was created.","example":"2025-07-08T12:34:56.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"The date the user was last updated.","example":"2025-07-08T12:34:56.000Z"},"wallet":{"description":"User wallet information.","nullable":true,"allOf":[{"$ref":"#/components/schemas/WalletResponseDto"}]}},"required":["id","username","displayName","isAdmin","bio","avatarUrl","bannerUrl","country","email","verifiedAt","isActive","canCreateCollectibles","actionToken","ipHash","referredByUserId","inviteCodesQuota","allowedToGenerateInviteCode","createdAt","updatedAt","wallet"]},"UserMeResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the user.","example":"123e4567-e89b-12d3-a456-426614174000"},"username":{"type":"string","description":"The username of the user.","example":"exampleuser1"},"displayName":{"type":"object","description":"The display name of the user.","example":"Conqr","nullable":true},"isAdmin":{"type":"boolean","description":"Whether the user is an admin.","example":true,"deprecated":true},"bio":{"type":"object","description":"User's custom bio.","example":"My name is Conqr and I like ducks.","nullable":true},"avatarUrl":{"type":"object","description":"The URL to the user's avatar.","example":"https://users.helix-cdn.com/123e4567-e89b-12d3-a456-426614174000/avatar","nullable":true},"bannerUrl":{"type":"object","description":"The URL to the user's banner.","example":"https://users.helix-cdn.com/123e4567-e89b-12d3-a456-426614174000/banner","nullable":true},"subscriptionTier":{"type":"string","description":"The account subscription tier used for profile benefits.","enum":["free","plus","gold","diamond"],"default":"free"},"country":{"type":"object","description":"User's country (self selected).","example":"US","nullable":true},"onlineStatusVisibility":{"type":"string","description":"Who can see this user online status and joinable presence.","enum":["me","friends","public"],"default":"friends"},"presenceShareActivity":{"type":"boolean","description":"Whether the user shares rich activity (current world/home/instance). When false, presence is online-only.","example":true,"default":true},"vaultAutoPublishGeneratedAssets":{"type":"boolean","description":"Whether assets this user generates are automatically catalogued as Vault resources (reusable across worlds, earning passive LIX on usage). Default ON. Settable via PATCH /users/me — and READABLE here, which is what lets a settings toggle render its own state instead of guessing.","example":true,"default":true},"contentMaturity":{"type":"string","description":"The most mature content this user sees in discovery (HYPR-5128). Listings cap at this value; a `maxContentMaturity` query param can only narrow further. Settable via PATCH /users/me — and readable here, so the settings picker can render its own state.","enum":["general","teen","mature","adult"],"default":"general"},"createdAt":{"format":"date-time","type":"string","description":"The date the user was created.","example":"2025-07-08T12:34:56.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"The date the user was last updated.","example":"2025-07-08T12:34:56.000Z"},"email":{"type":"string","description":"The email of the user.","example":"user@example.com"},"verifiedAt":{"type":"object","description":"The date when the user verified their email.","example":"2024-01-15T10:30:00Z","nullable":true},"wallet":{"description":"User wallet information.","nullable":true,"allOf":[{"$ref":"#/components/schemas/WalletResponseDto"}]},"acceptedEulaId":{"type":"object","description":"The ID of the EULA version that the user has accepted.","example":"123e4567-e89b-12d3-a456-426614174000","nullable":true},"eulaAcceptedAt":{"type":"object","description":"The date when the user accepted the EULA.","example":"2025-07-08T12:34:56.000Z","nullable":true},"hasAcceptedLatestEula":{"type":"boolean","description":"Whether the user has accepted the latest EULA version.","example":true},"acceptedPrivacyPolicyId":{"type":"object","description":"The ID of the Privacy Policy version that the user has accepted.","example":"123e4567-e89b-12d3-a456-426614174000","nullable":true},"privacyPolicyAcceptedAt":{"type":"object","description":"The date when the user accepted the Privacy Policy.","example":"2025-07-08T12:34:56.000Z","nullable":true},"hasAcceptedLatestPrivacyPolicy":{"type":"boolean","description":"Whether the user has accepted the latest Privacy Policy version.","example":true},"discordId":{"type":"object","description":"Discord user ID if account is linked.","example":"1234567890","nullable":true},"discordUsername":{"type":"object","description":"Discord username if account is linked.","example":"Username#0000","nullable":true},"discordConnectedAt":{"type":"object","description":"Date when Discord account was connected.","example":"2025-12-12T10:30:00Z","nullable":true}},"required":["id","username","displayName","isAdmin","bio","avatarUrl","bannerUrl","subscriptionTier","country","onlineStatusVisibility","presenceShareActivity","vaultAutoPublishGeneratedAssets","contentMaturity","createdAt","updatedAt","email","verifiedAt","wallet","acceptedEulaId","eulaAcceptedAt","hasAcceptedLatestEula","acceptedPrivacyPolicyId","privacyPolicyAcceptedAt","hasAcceptedLatestPrivacyPolicy","discordId","discordUsername","discordConnectedAt"]},"UserReviewResponseDto":{"type":"object","properties":{"id":{"type":"string","example":"b1e2c3d4-5678-1234-9abc-1234567890ab"},"packageId":{"type":"string","example":"c1d2e3f4-5678-1234-9abc-1234567890ab"},"userId":{"type":"string","example":"a1b2c3d4-5678-1234-9abc-1234567890ab"},"username":{"type":"string","example":"testuser"},"message":{"type":"string","example":"Great package!"},"score":{"type":"number","example":1},"createdAt":{"format":"date-time","type":"string","example":"2025-07-08T12:34:56.000Z"},"updatedAt":{"format":"date-time","type":"string","example":"2025-07-08T12:34:56.000Z"}},"required":["id","packageId","userId","username","score","createdAt","updatedAt"]},"UserReviewsCollectionResponseDto":{"type":"object","properties":{"items":{"description":"The items in the collection.","type":"array","items":{"$ref":"#/components/schemas/UserReviewResponseDto"}},"totalItems":{"type":"number","description":"The total number of items in the collection.","example":100},"pagination":{"description":"The pagination information.","allOf":[{"$ref":"#/components/schemas/PaginationResponseDto"}]},"pageInfo":{"description":"Keyset/cursor pagination info for infinite scroll.","allOf":[{"$ref":"#/components/schemas/PageInfoResponseDto"}]}},"required":["items","totalItems","pagination"]},"ErrorResponseDto":{"type":"object","properties":{"statusCode":{"type":"number","example":404},"error":{"type":"string","example":"Not Found"},"message":{"type":"string","example":"User not found."}},"required":["statusCode","error","message"]},"ImageRequestDto":{"type":"object","properties":{"mime":{"type":"string","description":"The mime type of the image.","example":"image/png","enum":["image/png","image/jpg","image/jpeg","image/webp"]},"data":{"type":"string","description":"The base64 encoded image data.","example":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+ip1sAAAAASUVORK5CYII="}},"required":["mime","data"]},"UpdateUserRequestDto":{"type":"object","properties":{"username":{"type":"string","description":"The new username of the user.","example":"exampleuser1","minLength":5,"maxLength":24,"nullable":false},"displayName":{"type":"string","description":"The new display name of the user, or null to clear it.","example":"Conqr","nullable":true,"minLength":2,"maxLength":24},"password":{"type":"string","description":"The new password of the user.","example":"password123","minLength":8,"maxLength":72,"nullable":false},"currentPassword":{"type":"string","description":"The current password, required alongside `password` when the account already has one. A first password (passwordless account bootstrap, HYPR-5042) needs no current password.","nullable":false},"bio":{"type":"string","description":"The new user bio, or null to clear it.","example":"My name is Conqr and I like ducks.","nullable":true,"maxLength":100},"country":{"type":"string","description":"The new country of the user, or null to clear it.","example":"US","nullable":true},"avatar":{"description":"The new avatar image data of the user.","allOf":[{"$ref":"#/components/schemas/ImageRequestDto"}]},"banner":{"description":"The new banner image data of the user.","allOf":[{"$ref":"#/components/schemas/ImageRequestDto"}]},"acceptedEulaId":{"type":"string","description":"The ID of the EULA version that the user accepts. Must be the latest version.","example":"123e4567-e89b-12d3-a456-426614174000","nullable":false},"acceptedPrivacyPolicyId":{"type":"string","description":"The ID of the Privacy Policy version that the user accepts. Must be the latest version.","example":"123e4567-e89b-12d3-a456-426614174000","nullable":false},"acceptedLatestFlag":{"type":"boolean","description":"Flag to automatically accept the latest EULA and Privacy Policy. When true, acceptedEulaId and acceptedPrivacyPolicyId are not required and the latest versions will be used automatically. Still respects ENFORCE_EULA_PRIVACY_POLICY environment variable.","example":true,"default":false},"onlineStatusVisibility":{"type":"string","description":"Who can see the user online status and joinable presence.","example":"public","enum":["me","friends","public"],"default":"public"},"presenceShareActivity":{"type":"boolean","description":"Whether to share rich activity (current world/home/instance) with permitted viewers. When false, presence is online-only (no activity).","example":true,"default":true},"vaultAutoPublishGeneratedAssets":{"type":"boolean","description":"Share generated assets to Vault by default. When on, assets produced while generating a world are automatically published to the Vault for use in other worlds and earn passive LIX based on usage. Turn it off to keep them out of the library (the world still uses them).","example":true,"default":true},"contentMaturity":{"type":"string","description":"The most mature content this user wants to see in discovery (HYPR-5128). Acts as a ceiling: listings never return content above it, and a `maxContentMaturity` query param can only narrow further. `adult` is NOT accepted while the platform ceiling sits at `mature` — no age verification exists (HYPR-5076 decision #1A), so accepting it would store a preference the filter then ignores.","example":"teen","enum":["general","teen","mature"],"default":"general"}}},"ImageResponseDto":{"type":"object","properties":{"key":{"type":"string","description":"The key of the image.","example":"Image_1"},"url":{"type":"string","description":"The URL of the image.","example":"https://images.helix-cdn.com/Image_1"}},"required":["key","url"]},"UploadMultipartPartDto":{"type":"object","properties":{"partNumber":{"type":"number","description":"Sequential part number starting at 1."},"partUrl":{"type":"string","description":"Presigned URL to upload this part with PUT."}},"required":["partNumber","partUrl"]},"PackageVersionFileResponseDto":{"type":"object","properties":{"key":{"type":"string","description":"File key used under a package version path.","example":"client"},"size":{"type":"number","description":"File size in bytes.","example":1024},"metadata":{"type":"object","description":"Arbitrary per-file metadata.","example":{"locale":"en"}},"uploadUrl":{"type":"string","description":"Upload URL for non-multipart upload. Present in create/update responses."},"downloadUrl":{"type":"string","description":"Download URL for retrieval responses."},"uploadMultipartUrls":{"description":"Multipart part URLs when file size exceeds single-upload threshold.","type":"array","items":{"$ref":"#/components/schemas/UploadMultipartPartDto"}}},"required":["key","size","metadata"]},"PackageVersionPartialResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the package version.","example":"7a65e3e1-4369-4486-ba2b-ce0d84d24508"},"packageId":{"type":"string","description":"The ID of the package.","example":"123e4567-e89b-12d3-a456-426614174000"},"revision":{"type":"number","description":"The revision number for this package version.","example":1},"name":{"type":"string","description":"[DEPRECATED] The name of the package version. Always returns \"0.0.0\".","example":"0.0.0","deprecated":true},"config":{"type":"object","description":"The configuration of the package version.","example":{"fieldOne":"valueOne","fieldTwo":"valueTwo"}},"clientSize":{"type":"number","description":"The client size of the package version.","example":37434163},"serverSize":{"type":"number","description":"The server size of the package version.","example":37434163},"editorSize":{"type":"number","description":"The editor size of the package version.","example":37434163},"metadataSize":{"type":"number","description":"The metadata size of the package version.","example":1024},"releaseNotes":{"type":"object","description":"Release notes describing changes for this version.","example":"Fixed bugs and improved performance.","nullable":true},"engineVersion":{"type":"string","description":"The supported engine version for this package version. Package versions do not select a platform independently; the current HELIX Unreal runtime target is Win64 only.","example":"5.7"},"clientUrl":{"type":"string","description":"The URL of the client pak file for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/client"},"serverUrl":{"type":"string","description":"The URL of the server pak file for this packageversion.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/server"},"editorUrl":{"type":"string","description":"The URL of the editor for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/editor"},"metadataUrl":{"type":"string","description":"The URL of the metadata for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/metadata"},"files":{"description":"Flexible package version files payload.","type":"array","items":{"$ref":"#/components/schemas/PackageVersionFileResponseDto"}},"createdAt":{"format":"date-time","type":"string","description":"The date and time the package version was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the package version was updated."},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the package version was published.","nullable":true},"dependencyIds":{"description":"The immediate upstream dependency IDs for this package version.","example":["a00db5c3-73b8-4f92-b7cd-7ee843b16dc3","45148b3b-a28a-411f-bb37-f4575e32b509"],"type":"array","items":{"type":"string"}},"dependentIds":{"description":"The immediate downstream dependents for this package version.","example":["174427b0-f3e2-4975-8599-1e9c49e7db53","2e85e458-6192-421f-b84e-7481c2050c53"],"type":"array","items":{"type":"string"}}},"required":["id","packageId","revision","name","config","clientSize","serverSize","editorSize","metadataSize","releaseNotes","engineVersion","clientUrl","serverUrl","editorUrl","metadataUrl","createdAt","updatedAt","publishedAt","dependencyIds","dependentIds"]},"PackageCollectionResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the package.","example":"123e4567-e89b-12d3-a456-426614174000"},"creatorId":{"type":"string","description":"The ID of the creator of the package.","example":"6fdbdb34-bd55-4d7b-8094-c72e9e0a4fa4"},"name":{"type":"string","description":"The name of the package.","example":"My Package"},"slug":{"type":"string","description":"The slug of the package.","example":"my-package"},"description":{"type":"string","description":"The description of the package.","example":"This is a description of my package."},"type":{"type":"string","description":"The type of the package.","example":"game"},"contentRating":{"type":"string","description":"The content rating of the package.","example":"Everyone"},"contentRatingStatus":{"type":"string","description":"The trust-and-safety review status of the content rating.","example":"pending_review"},"contentRatingDeclaredAt":{"type":"object","nullable":true},"contentRatingReviewedAt":{"type":"object","nullable":true},"previews":{"description":"The previews of the package.","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"tags":{"description":"The tags of the package.","example":["Sandbox","Roleplay","PvP"],"type":"array","items":{"type":"string"}},"downloads":{"type":"number","description":"The number of downloads of the package.","example":100},"currentRating":{"type":"number","description":"The current rating of the package.","example":4.5},"totalRatings":{"type":"number","description":"The total number of ratings of the package.","example":100},"isPrivate":{"type":"boolean","description":"Whether the package is private.","example":false},"engineVersion":{"type":"string","description":"The engine version supported by this package. All package versions inherit this value. The current HELIX Unreal runtime target is Win64 only.","example":"5.7"},"priceLix":{"type":"number","description":"The price in LIX for the package.","example":10.5},"thumbsUpPercentage":{"type":"string","example":"80%","description":"Percentage of thumbs up reviews."},"totalReviews":{"type":"number","description":"The total number of reviews for the package.","example":42},"serverCreationPermission":{"type":"string","description":"Who may create a persistent server for the world backing this package. Null when no world mirrors this package — treat as \"not allowed\" rather than assuming a default.","enum":["creator","collaborators","anyone","nobody"],"nullable":true,"example":"anyone"},"createdAt":{"format":"date-time","type":"string","description":"The date and time the package was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the package was updated."},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the package was published.","nullable":true},"lastReleaseAt":{"format":"date-time","type":"string","description":"The date and time of the last release (latest version) of the package.","nullable":true},"latestVersion":{"description":"The latest version of the package.","allOf":[{"$ref":"#/components/schemas/PackageVersionPartialResponseDto"}]},"creator":{"description":"The creator of the package.","allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]}},"required":["id","creatorId","name","slug","description","type","contentRating","contentRatingStatus","previews","tags","downloads","currentRating","totalRatings","isPrivate","engineVersion","priceLix","thumbsUpPercentage","totalReviews","createdAt","updatedAt","publishedAt","lastReleaseAt","latestVersion","creator"]},"PackageResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the package.","example":"123e4567-e89b-12d3-a456-426614174000"},"creatorId":{"type":"string","description":"The ID of the creator of the package.","example":"6fdbdb34-bd55-4d7b-8094-c72e9e0a4fa4"},"name":{"type":"string","description":"The name of the package.","example":"My Package"},"slug":{"type":"string","description":"The slug of the package.","example":"my-package"},"description":{"type":"string","description":"The description of the package.","example":"This is a description of my package."},"type":{"type":"string","description":"The type of the package.","example":"world"},"contentRating":{"type":"string","description":"The content rating of the package.","example":"Everyone"},"contentRatingStatus":{"type":"string","description":"The trust-and-safety review status of the content rating.","example":"pending_review"},"contentRatingDeclaredAt":{"type":"object","nullable":true},"contentRatingReviewedAt":{"type":"object","nullable":true},"previews":{"description":"The previews of the package.","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"tags":{"description":"The tags of the package.","example":["Sandbox","Roleplay","PvP"],"type":"array","items":{"type":"string"}},"priceLix":{"type":"number","description":"The price in Lix currency for the package.","example":99.99},"downloads":{"type":"number","description":"The number of downloads of the package.","example":100},"currentRating":{"type":"number","description":"The current rating of the package.","example":4.5},"totalRatings":{"type":"number","description":"The total number of ratings of the package.","example":100},"isPrivate":{"type":"boolean","description":"Whether the package is private.","example":false},"createdAt":{"format":"date-time","type":"string","description":"The date and time the package was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the package was updated."},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the package was published.","nullable":true}},"required":["id","creatorId","name","slug","description","type","contentRating","contentRatingStatus","previews","tags","priceLix","downloads","currentRating","totalRatings","isPrivate","createdAt","updatedAt","publishedAt"]},"ServerPackageWithDetailsResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the package version.","example":"7a65e3e1-4369-4486-ba2b-ce0d84d24508"},"packageId":{"type":"string","description":"The ID of the package.","example":"123e4567-e89b-12d3-a456-426614174000"},"revision":{"type":"number","description":"The revision number for this package version.","example":1},"name":{"type":"string","description":"[DEPRECATED] The name of the package version. Always returns \"0.0.0\".","example":"0.0.0","deprecated":true},"config":{"type":"object","description":"The configuration of the package version.","example":{"fieldOne":"valueOne","fieldTwo":"valueTwo"}},"clientSize":{"type":"number","description":"The client size of the package version.","example":37434163},"serverSize":{"type":"number","description":"The server size of the package version.","example":37434163},"editorSize":{"type":"number","description":"The editor size of the package version.","example":37434163},"metadataSize":{"type":"number","description":"The metadata size of the package version.","example":1024},"releaseNotes":{"type":"object","description":"Release notes describing changes for this version.","example":"Fixed bugs and improved performance.","nullable":true},"engineVersion":{"type":"string","description":"The supported engine version for this package version. Package versions do not select a platform independently; the current HELIX Unreal runtime target is Win64 only.","example":"5.7"},"clientUrl":{"type":"string","description":"The URL of the client pak file for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/client"},"serverUrl":{"type":"string","description":"The URL of the server pak file for this packageversion.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/server"},"editorUrl":{"type":"string","description":"The URL of the editor for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/editor"},"metadataUrl":{"type":"string","description":"The URL of the metadata for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/metadata"},"files":{"description":"Flexible package version files payload.","type":"array","items":{"$ref":"#/components/schemas/PackageVersionFileResponseDto"}},"createdAt":{"format":"date-time","type":"string","description":"The date and time the package version was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the package version was updated."},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the package version was published.","nullable":true},"dependencyIds":{"description":"The immediate upstream dependency IDs for this package version.","example":["a00db5c3-73b8-4f92-b7cd-7ee843b16dc3","45148b3b-a28a-411f-bb37-f4575e32b509"],"type":"array","items":{"type":"string"}},"dependentIds":{"description":"The immediate downstream dependents for this package version.","example":["174427b0-f3e2-4975-8599-1e9c49e7db53","2e85e458-6192-421f-b84e-7481c2050c53"],"type":"array","items":{"type":"string"}},"packageName":{"type":"string","description":"The name of the package.","example":"My Package"},"package":{"description":"The package details.","allOf":[{"$ref":"#/components/schemas/PackageResponseDto"}]}},"required":["id","packageId","revision","name","config","clientSize","serverSize","editorSize","metadataSize","releaseNotes","engineVersion","clientUrl","serverUrl","editorUrl","metadataUrl","createdAt","updatedAt","publishedAt","dependencyIds","dependentIds","packageName","package"]},"ServerResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the server.","example":"da1c4709-9723-4df5-9587-1cabb675611c"},"ownerId":{"type":"string","description":"The ID of the owner of the server.","example":"6fdbdb34-bd55-4d7b-8094-c72e9e0a4fa4"},"slug":{"type":"string","description":"The slug of the server.","example":"my-server"},"name":{"type":"string","description":"The name of the server.","example":"My Server"},"description":{"type":"string","description":"The description of the server.","example":"This is a description of my server."},"tags":{"description":"The tags of the server.","example":["Sandbox","Roleplay","PvP"],"type":"array","items":{"type":"string"}},"contentRating":{"type":"string","description":"The content rating of the server.","example":"Everyone"},"contentRatingStatus":{"type":"string","description":"The trust-and-safety review status of the content rating.","example":"pending_review"},"contentRatingDeclaredAt":{"type":"object","nullable":true},"contentRatingReviewedAt":{"type":"object","nullable":true},"gameMode":{"type":"string","description":"The game mode of the server.","example":"Sandbox"},"hostingType":{"type":"string","description":"The hosting type of the server.","example":"Dedicated"},"gameVersion":{"type":"string","description":"The game version of the server.","example":"1.0.0"},"worldId":{"type":"string","description":"The world ID of the server.","example":"e4412457-5bd4-44e2-a219-80fd3944d378"},"ipAddress":{"type":"string","description":"The IP address of the server.","example":"127.0.0.1"},"port":{"type":"number","description":"The port of the server.","example":7777},"currentPlayers":{"type":"number","description":"The current number of players on the server.","example":10},"maxPlayers":{"type":"number","description":"The maximum number of players on the server.","example":64},"playerIds":{"description":"The IDs of the players on the server.","example":["9669d149-349e-4bca-a58a-c8e1614bbc63","f3735be6-0ebc-4007-a9c7-1fe1ad0884b6","4b7bc58d-5906-404f-82a6-0c1f52d489d2"],"type":"array","items":{"type":"string"}},"status":{"type":"string","description":"The status of the server.","example":"Online"},"visits":{"type":"number","description":"The number of visits to the server.","example":12345},"currentRating":{"type":"number","description":"The current rating of the server.","example":4.5},"totalRatings":{"type":"number","description":"The total number of ratings for the server.","example":1337},"previews":{"description":"The previews of the package.","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"region":{"type":"string","description":"The server's region (2-letter ISO code).","example":"US","nullable":true},"heartbeatAddress":{"type":"object","description":"Heartbeat server address (provisioned servers only).","nullable":true},"nucleusIport":{"type":"object","description":"Nucleus internal port (provisioned servers only).","nullable":true},"workspaceId":{"type":"object","description":"Workspace ID (provisioned servers only).","nullable":true},"levelAsset":{"type":"object","description":"Level asset path (provisioned servers only).","nullable":true},"sideloadPaks":{"type":"object","description":"Comma-separated sideload pak files (provisioned servers only).","nullable":true},"systemDependencies":{"type":"object","description":"System dependencies (provisioned servers only).","nullable":true},"isPrivate":{"type":"boolean","description":"Whether the server is private.","example":false},"isFavorited":{"type":"boolean","description":"Whether the current authenticated user has favorited this server.","example":false},"whitelist":{"description":"Users whitelisted to access this private server.","type":"array","items":{"$ref":"#/components/schemas/UserResponseDto"}},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the server was published.","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"The date and time the server was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the server was updated."},"lastTimeOnline":{"format":"date-time","type":"string","description":"The date and time the server was last online (last heartbeat received).","nullable":true},"owner":{"description":"The owner of the server.","allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]},"world":{"description":"The world definition for the server.","allOf":[{"$ref":"#/components/schemas/ServerPackageWithDetailsResponseDto"}]}},"required":["id","ownerId","slug","name","description","tags","contentRating","contentRatingStatus","gameMode","hostingType","gameVersion","worldId","ipAddress","port","currentPlayers","maxPlayers","playerIds","status","visits","currentRating","totalRatings","previews","region","isPrivate","whitelist","publishedAt","createdAt","updatedAt","lastTimeOnline","owner","world"]},"InstantWorldCreatorResponseDto":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"object","nullable":true},"avatarUrl":{"type":"object","nullable":true}},"required":["id","username","displayName","avatarUrl"]},"InstantWorldResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"World id."},"slug":{"type":"string","description":"Globally-unique URL slug."},"engine":{"type":"string","description":"Runtime that delivers this world: 'web' (HELIX Instant browser build) or 'unreal' (legacy Unreal download).","enum":["web","unreal"]},"title":{"type":"string","description":"Display name."},"description":{"type":"object","description":"Short world description shown in discovery.","nullable":true},"category":{"type":"string","description":"Editorial category."},"tags":{"description":"Lightweight editorial/discovery tags.","type":"array","items":{"type":"string"}},"creatorId":{"type":"string","description":"Owning creator id."},"projectId":{"type":"object","description":"Owner-only. The Dreamer project/session this world is edited through — the key that resumes the creator's editing session. Null on public responses and for worlds with no Dreamer project (CLI/MCP/bundle uploads): null means the world has no resumable session, never 'start a new one'.","nullable":true},"creator":{"description":"Public creator profile summary for attribution. Present when the creator row exists.","nullable":true,"allOf":[{"$ref":"#/components/schemas/InstantWorldCreatorResponseDto"}]},"metadata":{"type":"object","description":"Non-authoritative listing metadata. Includes creator attribution keys for clients that still normalize worlds from metadata.","additionalProperties":true},"status":{"type":"string","description":"Lifecycle status.","enum":["draft","published","unlisted","suspended"]},"activeBuildId":{"type":"object","description":"Current active Build id, if any. Populated for EVERY engine — the mapper assigns it straight off the row. (This previously read \"engine=web only\", which was false: engine=unreal worlds carry it, and it is the field the PC client uses to resolve a Build's signed manifest.)","nullable":true},"networkMode":{"type":"string","description":"Whether the active Shared-Runtime Build needs a server. Null when there is no readable active Build, or when the Build is a web bundle (which has no Unreal network mode) — null means UNKNOWN/not-applicable and must never be read as single_player. ROUTING HINT ONLY: this response is unsigned and cacheable, so it may drift from the Build actually launched. The platform-countersigned Build manifest remains the sole authority at launch time.","enum":["single_player","listen","managed"],"nullable":true},"legacyPackageId":{"type":"object","description":"For engine=unreal: the originating packages row that owns the UE delivery chain. Null for engine=web.","nullable":true},"enginePayload":{"type":"object","description":"For engine=unreal: denormalized UE delivery metadata ({ engineVersion, latestRevision, clientSize }). Null for engine=web.","additionalProperties":true,"nullable":true},"hasActiveBuild":{"type":"boolean","description":"Whether the world has an active (published) build."},"contentRating":{"type":"string","description":"Self-declared content rating."},"contentRatingStatus":{"type":"string","description":"Trust-and-safety review status for the content rating."},"supportsMobile":{"type":"boolean","description":"Whether the world is playable on mobile."},"requiresAuth":{"type":"boolean","description":"Whether players must log in before playing."},"multiplayer":{"type":"object","description":"Whether the world is multiplayer, from the ACTIVE BUILD'S MANIFEST (the `multiplayer` permission) — the same source the room-credential mint trusts. Null when the world has no readable active build, i.e. UNKNOWN: clients must render nothing for null, never \"single-player\".","nullable":true},"maxPlayers":{"type":"object","description":"Declared player slots per room from the active build's manifest (`maxPlayers`; 1 = single-player). Null when there is no readable active build or the stored manifest omits it. Note the room server caps CONCURRENT players per room and spills the rest into further instances, so this is the declared design value, not a live capacity.","nullable":true,"example":16},"visitCount":{"type":"number","description":"Number of public detail visits."},"uniqueVisitorCount":{"type":"object","description":"Distinct-visitor count (unique actors who entered the world). Populated on the single-world detail response; null on list responses.","nullable":true},"playersOnline":{"type":"object","description":"Players currently in this world across all live room instances (multiplayer worlds on public list/detail responses). Null when the world is single-player or live metrics are unavailable — clients must render nothing for null, never a fabricated count.","nullable":true},"isFeatured":{"type":"boolean","description":"Whether this world is editorially featured."},"featuredRank":{"type":"object","description":"Optional editorial ordering rank for featured sections.","nullable":true},"isOfficial":{"type":"boolean","description":"Whether this is a backend-trusted official world."},"coinEarnEnabled":{"type":"boolean","description":"Whether this world can credit Coins through world sessions."},"coinSpendEnabled":{"type":"boolean","description":"Whether this world can debit Coins through world sessions."},"totalReviews":{"type":"number","description":"Total number of reviews for this world."},"thumbsUpCount":{"type":"number","description":"Count of thumbs-up (positive) reviews."},"thumbsDownCount":{"type":"number","description":"Count of thumbs-down (negative) reviews."},"thumbsUpPercentage":{"type":"string","description":"Thumbs-up share as a display string (\"75%\" or \"N/A\")."},"serverCreationPermission":{"type":"string","description":"Who may stand up a persistent server for this world."},"playUrl":{"type":"object","description":"Shareable website play page for this world (FRONTEND_URL/play/<slug>). Null until published.","nullable":true},"bundleUrl":{"type":"object","description":"CDN URL of the active build entry point — what the play page iframes. Null until published.","nullable":true},"sceneDocumentUrl":{"type":"object","description":"Authoritative HELIX Scene v2 document for a native Scene World. Null for legacy iframe and Shared-Runtime builds.","nullable":true},"sceneId":{"type":"object","nullable":true},"sceneRevision":{"type":"object","nullable":true},"sceneIntegritySha256":{"type":"object","nullable":true},"sceneProfileId":{"type":"object","nullable":true},"thumbnailUrl":{"type":"string","description":"World thumbnail URL. A creator-uploaded custom image when one is set; otherwise the deterministic auto-generated per-world SVG. Never a shared static placeholder."},"hasCustomThumbnail":{"type":"boolean","description":"Whether the thumbnail is a creator-uploaded custom image (vs the auto-generated SVG fallback)."},"previewMediaUrl":{"type":"object","description":"CDN URL of the optional creator-uploaded preview image. Null when unset.","nullable":true},"previewYoutubeId":{"type":"object","description":"YouTube video id (11 chars) of the optional preview video. Null when unset. Clients should embed it via youtube-nocookie; `previewYoutubeUrl` is the ready-made embed URL.","nullable":true,"example":"dQw4w9WgXcQ"},"previewYoutubeUrl":{"type":"object","description":"Privacy-friendly embed URL for `previewYoutubeId`, or null when no video is set. Derived server-side so every client embeds the same canonical host.","nullable":true,"example":"https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ"},"bundleSizeBytes":{"type":"object","description":"Total download size of the world's active build bundle, in bytes. Null when the world has no active build (nothing to download yet). Read from the build row the response already loads to resolve `bundleUrl`, so it adds no query.","nullable":true,"example":5242880},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp."},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp."}},"required":["id","slug","engine","title","description","category","tags","creatorId","projectId","creator","metadata","status","activeBuildId","networkMode","legacyPackageId","enginePayload","hasActiveBuild","contentRating","contentRatingStatus","supportsMobile","requiresAuth","multiplayer","maxPlayers","visitCount","uniqueVisitorCount","playersOnline","isFeatured","featuredRank","isOfficial","coinEarnEnabled","coinSpendEnabled","totalReviews","thumbsUpCount","thumbsDownCount","thumbsUpPercentage","serverCreationPermission","playUrl","bundleUrl","sceneDocumentUrl","sceneId","sceneRevision","sceneIntegritySha256","sceneProfileId","thumbnailUrl","hasCustomThumbnail","previewMediaUrl","previewYoutubeId","previewYoutubeUrl","bundleSizeBytes","createdAt","updatedAt"]},"UniversalItemCreatorResponseDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"33333333-3333-4333-8333-333333333333"},"username":{"type":"string","example":"helixuser"},"displayName":{"type":"object","nullable":true,"example":"Helix User"},"avatarUrl":{"type":"object","nullable":true,"example":"https://cdn.helixgame.com/avatars/helixuser.png"}},"required":["id","username","displayName","avatarUrl"]},"UniversalItemMarketplaceDistributionResponseDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"priceLix":{"type":"number","example":1500},"currency":{"type":"string","enum":["LIX","COINS"],"example":"LIX"},"priceCoins":{"type":"object","nullable":true,"example":150},"maxPerPlayer":{"type":"object","nullable":true,"example":1},"maxClaims":{"type":"object","nullable":true,"example":500},"issuedCount":{"type":"number","example":12},"startsAt":{"type":"object","nullable":true},"endsAt":{"type":"object","nullable":true}},"required":["id","priceLix","currency","priceCoins","maxPerPlayer","maxClaims","issuedCount","startsAt","endsAt"]},"UniversalItemAssetFileResponseDto":{"type":"object","properties":{"key":{"type":"string","description":"File key/path under the build.","example":"ExampleJacket-Windows.utoc"},"size":{"type":"number","description":"File size in bytes.","example":800000},"mimeType":{"type":"object","nullable":true,"description":"File MIME type.","example":"application/octet-stream"},"sha256":{"type":"object","nullable":true,"description":"Lowercase-hex SHA-256 of the file, when the publisher declared one. A non-null value here has been VERIFIED against the stored bytes at finalize — the finalize fails otherwise — so a client may use it to check its own download. Null means no digest was declared, not that the file is bad.","example":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},"metadata":{"type":"object","example":{"channel":"diffuse"}},"url":{"type":"string","description":"Public CDN URL for retrieval.","example":"https://ue.items.helix-cdn.com/universal-items/b3d1f2a4/a1b2c3d4/unreal/ExampleJacket-Windows.utoc"},"uploadUrl":{"type":"string","description":"Presigned PUT URL for this file. Present only in create/update responses.","example":"https://<r2-bucket>.r2.cloudflarestorage.com/universal-items/b3d1f2a4/a1b2c3d4/unreal/ExampleJacket-Windows.utoc?X-Amz-Signature=..."}},"required":["key","size","mimeType","sha256","metadata","url"]},"UniversalItemAssetResponseDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"},"rendition":{"type":"string","description":"Which build this row represents.","example":"web"},"cdnUrl":{"type":"string","description":"Web build CDN URL (empty for an Unreal-only asset).","example":"https://web.items.helix-cdn.com/universal-items/b3d1f2a4/a1b2c3d4/web/neon-lounge-chair.glb"},"mimeType":{"type":"string","description":"Web build MIME type.","example":"model/gltf-binary"},"sizeBytes":{"type":"number","description":"Web build size in bytes.","example":204800},"status":{"type":"string","description":"Async pipeline status (awaiting_upload → pending → processing → ready | rejected | failed).","example":"ready"},"engineVersion":{"type":"object","nullable":true,"description":"Unreal engine version this build was cooked for. Always populated for an `unreal` rendition (defaults to 5.7); always null for every other rendition.","example":null},"targetPlatforms":{"type":"array","description":"HELIX-supported UE cook targets this build ships. Currently only Win64 is accepted. Always present; EMPTY when undeclared or when the rendition is not `unreal` — never null, so \"nothing declared\" has exactly one representation.","example":[],"items":{"type":"string","enum":["Win64"]}},"files":{"description":"Files of the multi-file build (the Unreal build). Each carries a CDN url and, on create/update, a presigned uploadUrl.","example":[],"type":"array","items":{"$ref":"#/components/schemas/UniversalItemAssetFileResponseDto"}},"uploadUrl":{"type":"string","description":"Presigned PUT URL for the WEB build. Present only in create/update responses (PUT the bytes here, then call finalize).","example":"https://<r2-bucket>.r2.cloudflarestorage.com/universal-items/b3d1f2a4/a1b2c3d4/web/neon-lounge-chair.glb?X-Amz-Signature=..."},"metadata":{"type":"object","description":"Verification / optimization / pipeline metadata.","example":{"triangles":4820,"optimization":{"status":"done","ktx2Applied":true}}}},"required":["id","rendition","cdnUrl","mimeType","sizeBytes","status","engineVersion","targetPlatforms","files","metadata"]},"UniversalItemResponseDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b3d1f2a4-5c6d-4e7f-8a9b-0c1d2e3f4a5b"},"slug":{"type":"string","example":"neon-lounge-chair"},"title":{"type":"string","example":"Neon Lounge Chair"},"description":{"type":"object","nullable":true,"example":"A glowing mid-century lounge chair that lights up your room."},"creatorId":{"type":"object","nullable":true,"format":"uuid","description":"The creator user id (null for a platform/system item).","example":"33333333-3333-4333-8333-333333333333"},"creator":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/UniversalItemCreatorResponseDto"}]},"collectibleId":{"type":"object","nullable":true,"description":"Linked scarce collectible template, if this item is collectible-backed.","example":null},"vaultAssetId":{"type":"object","nullable":true,"format":"uuid","description":"Immutable Vault resource currently backing this managed Item, when versioned."},"kind":{"type":"string","example":"home_item"},"category":{"type":"string","example":"furniture"},"subCategory":{"type":"object","nullable":true,"example":"seating"},"slot":{"type":"object","nullable":true,"description":"Character-Creator cosmetic slot for wearables (gameplay tag). Null for non-wearables.","example":"Cosmetic.Slot.Clothing.Top"},"genders":{"description":"Character-Creator gender(s) this item is authored for. Always present; an EMPTY array for kinds nothing wears, and for wearables published before cc_genders existed. Never null — \"no genders\" has exactly one representation.","example":["male","female"],"type":"array","items":{"type":"string"}},"emoteCategory":{"type":"string","nullable":true,"enum":["regular","sit","lie"],"description":"Which emote slot family this performance belongs to. Null for every kind but emote. A client needs it to know which of the ten slots an owned emote may go in — the equip call cross-checks it.","example":"regular"},"slotType":{"type":"object","nullable":true,"description":"ADD-ONS ONLY. The single opening this add-on occupies. Null everywhere else.","example":"vehicle.exhaust@1"},"fits":{"type":"object","description":"ADD-ONS ONLY. The proved `fits` block. An absent `only` means UNIVERSAL — the client renders \"Fits: any vehicle\" from that, and a computed count from `GET :id/fits` otherwise. `{}` on every other kind."},"hostKind":{"type":"object","nullable":true,"description":"vehicle | character | home | world. Present on BOTH a base (from its declared host) and an add-on (from its slot type), which is what makes \"things that fit something you own\" a single indexed query."},"surfaceDigest":{"type":"object","nullable":true,"description":"The item's CURRENTLY published surface digest. An owned instance carries the PINNED one; the two differing means the base has been republished since that build was composed."},"slotCount":{"type":"number","description":"How many openings this item publishes. 0 for anything that is not a host."},"badges":{"type":"object","description":"DERIVED SERVER-SIDE, never accepted from a client. `helix` = published by HELIX itself. `official` is a relation between an add-on and a BASE, so it is null here and resolved by the per-base fitment routes."},"tags":{"example":["glow","mid-century"],"type":"array","items":{"type":"string"}},"usage":{"type":"string","example":"place"},"status":{"type":"string","description":"Lifecycle status. Only published items are publicly listed/purchasable.","example":"published"},"reviewStatus":{"type":"string","enum":["under_review"],"description":"Present only on the creator’s own moderation-suspended item: the item is held for review, not deleted. Which rule fired is deliberately not exposed (HYPR-5170).","example":"under_review"},"reviewStartedAt":{"type":"object","nullable":true,"description":"When the review hold started (null when the hold carries no timestamp).","example":null},"contentRating":{"type":"string","example":"everyone"},"contentRatingStatus":{"type":"string","example":"pending_review"},"contentRatingDeclaredAt":{"type":"object","nullable":true,"example":"2026-07-03T18:24:00.000Z"},"contentRatingReviewedAt":{"type":"object","nullable":true,"example":null},"priceLix":{"type":"object","nullable":true,"deprecated":true,"description":"Legacy compatibility projection. Definitions are unpriced, so new records return null; resolve acquisition policy from an Item Distribution.","example":null},"marketplaceDistributions":{"description":"Live Marketplace acquisition routes for this definition. Claim/Buy must use the exact distribution id.","type":"array","items":{"$ref":"#/components/schemas/UniversalItemMarketplaceDistributionResponseDto"}},"publishFeeLix":{"type":"number","description":"One non-refundable Publish fee charged when the definition first becomes public (LIX).","example":80},"publishFeeTransactionId":{"type":"object","nullable":true,"description":"Economy transaction id of the settled Publish fee.","example":null},"publishFeeStatus":{"type":"string","description":"Publish fee settlement state (none or paid).","example":"none"},"isGiftable":{"type":"boolean","example":false},"isCollectible":{"type":"boolean","example":false},"maxOwnablePerUser":{"type":"object","nullable":true,"description":"Per-user ownership cap (null = unlimited).","example":null},"supply":{"type":"object","nullable":true,"description":"Global supply cap (null = unlimited).","example":null},"mintedCount":{"type":"object","nullable":true,"example":12},"properties":{"type":"object","example":{"emitsLight":true,"lightColor":"#39ff14"}},"metadata":{"type":"object","example":{"assetGroupId":"b3d1f2a4","snapSurface":"ground"}},"assets":{"type":"array","items":{"$ref":"#/components/schemas/UniversalItemAssetResponseDto"}},"viewCount":{"type":"number","description":"Total number of unique-per-day views (marketplace/detail opens) this item has received.","example":128},"createdAt":{"format":"date-time","type":"string","example":"2026-07-03T18:24:00.000Z"},"updatedAt":{"format":"date-time","type":"string","example":"2026-07-03T18:24:00.000Z"}},"required":["id","slug","title","description","creatorId","creator","collectibleId","vaultAssetId","kind","category","subCategory","slot","genders","emoteCategory","slotType","fits","hostKind","surfaceDigest","slotCount","badges","tags","usage","status","contentRating","contentRatingStatus","contentRatingDeclaredAt","contentRatingReviewedAt","priceLix","marketplaceDistributions","publishFeeLix","publishFeeTransactionId","publishFeeStatus","isGiftable","isCollectible","maxOwnablePerUser","supply","mintedCount","properties","metadata","assets","viewCount","createdAt","updatedAt"]},"SceneDocumentIntegrityResponseDto":{"type":"object","properties":{"sha256":{"type":"string","description":"Lowercase SHA-256 of the Scene v2 RFC 8785 canonical payload with its top-level integrity field omitted."}},"required":["sha256"]},"SceneDocumentReferenceResponseDto":{"type":"object","properties":{"url":{"type":"string"},"id":{"type":"string"},"revision":{"type":"string"},"integrity":{"$ref":"#/components/schemas/SceneDocumentIntegrityResponseDto"}},"required":["url","id","revision","integrity"]},"HomeShellItemResponseDto":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"thumbnailUrl":{"type":"object","nullable":true},"webCompatible":{"type":"boolean","description":"A ready compiled Web Home exists, so browser Preview and Move In are supported."},"unrealCompatible":{"type":"boolean","description":"A ready Unreal rendition exists for the HELIX PC client."}},"required":["id","slug","title","thumbnailUrl","webCompatible","unrealCompatible"]},"HomePlacementResponseDto":{"type":"object","properties":{"id":{"type":"string"},"homeId":{"type":"string"},"itemId":{"type":"string"},"inventoryItemId":{"type":"object","nullable":true},"transform":{"type":"object"},"state":{"type":"object"},"metadata":{"type":"object"},"equipped":{"type":"boolean","description":"Whether the placed instance is currently equipped (worn). A placed item that is equipped elsewhere still occupies its spot in the home but is rendered ghosted (low opacity) by the client. Requires the inventoryItem relation to be loaded; defaults to false otherwise."},"canvasAssetId":{"type":"object","nullable":true,"description":"For a canvas item (poster / picture frame): the moderated image asset id bound to this placed copy, read from the linked inventory instance's state.canvasAssetId. Null when none is set."},"canvasAssetUrl":{"type":"object","nullable":true,"description":"The resolved our-hosted URL for canvasAssetId (deterministic; never a foreign URL). The client binds this texture to the item's 'canvas' material slot. Null when no canvas image is set."},"item":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/UniversalItemResponseDto"}]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","homeId","itemId","inventoryItemId","transform","state","metadata","equipped","canvasAssetId","canvasAssetUrl","item","createdAt","updatedAt"]},"HomeResponseDto":{"type":"object","properties":{"id":{"type":"string"},"ownerId":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"object","nullable":true},"visibility":{"type":"string"},"category":{"type":"string"},"contentRating":{"type":"string"},"contentRatingStatus":{"type":"string"},"contentRatingDeclaredAt":{"type":"object","nullable":true},"contentRatingReviewedAt":{"type":"object","nullable":true},"baseTemplateId":{"type":"object","nullable":true},"shellInventoryItemId":{"type":"object","nullable":true,"description":"The owned inventory instance that is this home's shell. Null for legacy template homes and for a home whose shell has been moved out of."},"shellBundleUrl":{"type":"object","nullable":true,"description":"URL of this home's COMPILED shell bundle (`world.json`) — the building the runtime loads. Resolved from the shell inventory instance‘s catalog item. NULL means the shell has not compiled yet, and a client must say so: there is no fallback shell, because walking someone through a home that is not theirs is worse than making them wait."},"sceneDocumentUrl":{"type":"object","nullable":true,"description":"Immutable HELIX Scene v2 entry for this home's shell. New Web and Unreal runtimes load this URL. Null means this shell has not been migrated; legacy clients may explicitly use shellBundleUrl."},"sceneDocument":{"nullable":true,"description":"Cache-safe immutable Scene v2 identity. Native clients verify the downloaded document against this digest and key caches by id, revision, and digest rather than URL.","allOf":[{"$ref":"#/components/schemas/SceneDocumentReferenceResponseDto"}]},"shellItem":{"nullable":true,"description":"The marketplace Home this residence uses. Null for legacy built-in templates.","allOf":[{"$ref":"#/components/schemas/HomeShellItemResponseDto"}]},"isActive":{"type":"boolean","description":"You live here — this home occupies one of your slots. Ownership is unlimited; slots limit occupancy."},"isLocked":{"type":"boolean","description":"Frozen because your plan no longer covers this many homes. Every item inside stays exactly where it is; reactivating restores it untouched."},"hasSavedLayout":{"type":"boolean","description":"This home has a saved layout from a previous move-out, so Restore Layout has something to put back."},"savedLayoutItemCount":{"type":"object","nullable":true,"description":"Number of items in the saved layout, or null when there is none."},"lastEnteredAt":{"type":"object","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"previewImageUrl":{"type":"object","nullable":true},"thumbnailUrl":{"type":"string","description":"A card image that is NEVER null — worlds have had this since Item 10, homes did not, which is why every home card rendered a blank grey placeholder (HYPR-5029). Prefers the stored preview URL, then a real (non-data:) metadata thumbnail URL, then the shell item art, and falls back to the same deterministic generated cover art worlds use. Present on LIST responses (unlike the captured showcase media, which lives in metadata and is stripped from lists for payload size)."},"isDefault":{"type":"boolean"},"slotIndex":{"type":"number"},"visitCount":{"type":"number"},"placedItemCount":{"type":"number"},"thumbsUpCount":{"type":"number","description":"Number of thumbs up (likes) on this home."},"thumbsDownCount":{"type":"number","description":"Number of thumbs down (dislikes) on this home."},"thumbsUpPercentage":{"type":"string","description":"Thumbs up percentage as a string, e.g. \"75%\" or \"N/A\"."},"viewerVote":{"type":"object","nullable":true,"description":"The requesting user's own vote (1, -1) or null when unauthenticated or not yet voted."},"estimatedLixValue":{"type":"number"},"metadata":{"type":"object"},"publishedAt":{"type":"object","nullable":true},"placements":{"type":"array","items":{"$ref":"#/components/schemas/HomePlacementResponseDto"}},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","ownerId","slug","title","description","visibility","category","contentRating","contentRatingStatus","contentRatingDeclaredAt","contentRatingReviewedAt","baseTemplateId","shellInventoryItemId","shellBundleUrl","sceneDocumentUrl","sceneDocument","shellItem","isActive","isLocked","hasSavedLayout","savedLayoutItemCount","lastEnteredAt","tags","previewImageUrl","thumbnailUrl","isDefault","slotIndex","visitCount","placedItemCount","thumbsUpCount","thumbsDownCount","thumbsUpPercentage","viewerVote","estimatedLixValue","metadata","publishedAt","placements","createdAt","updatedAt"]},"CreateUserReviewRequestDto":{"type":"object","properties":{"packageId":{"type":"string","description":"ID of the package to review","example":"c1d2e3f4-5678-1234-9abc-1234567890ab"},"message":{"type":"string","description":"Review message","maxLength":500,"example":"Great package!"},"score":{"type":"number","description":"Score (+1 for thumbs up, -1 for thumbs down)","enum":[1,-1],"example":1}},"required":["packageId","score"]},"UpdateUserReviewRequestDto":{"type":"object","properties":{"message":{"type":"string","description":"Review message","maxLength":500,"example":"Great package!"},"score":{"type":"number","description":"Score (+1 for thumbs up, -1 for thumbs down)","enum":[1,-1],"example":1}}},"WalletMeResponseDto":{"type":"object","properties":{"wallet_id":{"type":"string","description":"The unique identifier of the wallet.","example":"wallet_123456789"},"user_id":{"type":"string","description":"The unique identifier of the user who owns the wallet.","example":"user_987654321"},"wallet_type":{"type":"string","description":"The type of the wallet.","example":"user"},"system_wallet_name":{"type":"string","description":"The name of the system wallet (if applicable).","example":"marketplace_commission"},"withdrawable_balance":{"type":"number","description":"The withdrawable balance of the wallet.","example":100.5},"non_withdrawable_balance":{"type":"number","description":"The non-withdrawable balance of the wallet.","example":25.75},"pending_withdrawable_balance":{"type":"number","description":"The pending withdrawable balance of the wallet (funds that will become withdrawable after maturity period).","example":50},"currency":{"type":"string","description":"The currency of the wallet.","example":"USD"},"status":{"type":"string","description":"The status of the wallet.","example":"active"},"version":{"type":"number","description":"The version of the wallet for optimistic locking.","example":1},"created_at":{"type":"string","description":"The creation timestamp of the wallet.","example":"2024-01-15T10:30:00Z"},"updated_at":{"type":"string","description":"The last update timestamp of the wallet.","example":"2024-01-15T15:45:00Z"},"spendable_balance":{"type":"number","description":"Total LIX available to spend now (withdrawable plus non-withdrawable).","example":126.25},"pending_earnings_balance":{"type":"number","description":"Earned LIX still completing its maturity period.","example":50},"available_to_cash_out_balance":{"type":"number","description":"Mature earned LIX eligible for a future payout request. This is not proof that a payout endpoint is available.","example":100.5},"cash_out_eligible":{"type":"boolean","description":"Whether the wallet status and mature balance make the amount payout-eligible. This does not imply that a payout request endpoint is available.","example":true}},"required":["wallet_id","wallet_type","withdrawable_balance","non_withdrawable_balance","pending_withdrawable_balance","currency","status","version","created_at","updated_at","spendable_balance","pending_earnings_balance","available_to_cash_out_balance","cash_out_eligible"]},"DebugWalletTopUpRequestDto":{"type":"object","properties":{"amount":{"type":"number","description":"Positive integer LIX amount to add to the caller wallet.","example":1000},"reason":{"type":"object","nullable":true,"description":"Optional note shown as debug metadata on the transaction."}},"required":["amount"]},"CreatorDto":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"}},"required":["id","username"]},"EulaResponseDto":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"versionNumber":{"type":"number"},"createdBy":{"$ref":"#/components/schemas/CreatorDto"},"updatedBy":{"$ref":"#/components/schemas/CreatorDto"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","title","content","versionNumber","createdBy","updatedBy","createdAt","updatedAt"]},"EulaAcceptanceStatusDto":{"type":"object","properties":{"hasAcceptedEula":{"type":"boolean","description":"Whether the user has accepted any EULA","example":true},"hasAcceptedLatestVersion":{"type":"boolean","description":"Whether the user has accepted the latest EULA version","example":false},"acceptedVersion":{"type":"object","description":"The version number of the EULA the user has accepted (null if none)","example":1,"nullable":true},"eulaAcceptedAt":{"type":"object","description":"The date when the user accepted the EULA (null if none)","example":"2025-11-21T12:34:56.000Z","nullable":true},"latestVersion":{"type":"number","description":"The latest available EULA version number","example":2},"latestEulaId":{"type":"string","description":"The ID of the latest EULA","example":"123e4567-e89b-12d3-a456-426614174000"}},"required":["hasAcceptedEula","hasAcceptedLatestVersion","acceptedVersion","eulaAcceptedAt","latestVersion","latestEulaId"]},"CreateEulaDto":{"type":"object","properties":{"title":{"type":"string","description":"The title of the EULA","example":"End User License Agreement","maxLength":255},"content":{"type":"string","description":"The full content of the EULA","example":"This is the full text of the End User License Agreement..."}},"required":["title","content"]},"UpdateEulaDto":{"type":"object","properties":{"title":{"type":"string","description":"The title of the EULA","example":"End User License Agreement","maxLength":255},"content":{"type":"string","description":"The full content of the EULA","example":"This is the updated full text of the End User License Agreement..."}}},"PrivacyPolicyResponseDto":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"versionNumber":{"type":"number"},"createdBy":{"$ref":"#/components/schemas/CreatorDto"},"updatedBy":{"$ref":"#/components/schemas/CreatorDto"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","title","content","versionNumber","createdBy","updatedBy","createdAt","updatedAt"]},"PrivacyPolicyAcceptanceStatusDto":{"type":"object","properties":{"hasAcceptedPrivacyPolicy":{"type":"boolean","description":"Whether the user has accepted any Privacy Policy","example":true},"hasAcceptedLatestVersion":{"type":"boolean","description":"Whether the user has accepted the latest Privacy Policy version","example":false},"acceptedVersion":{"type":"object","description":"The version number of the Privacy Policy the user has accepted (null if none)","example":1,"nullable":true},"privacyPolicyAcceptedAt":{"type":"object","description":"The date when the user accepted the Privacy Policy (null if none)","example":"2025-11-21T12:34:56.000Z","nullable":true},"latestVersion":{"type":"number","description":"The latest available Privacy Policy version number","example":2},"latestPrivacyPolicyId":{"type":"string","description":"The ID of the latest Privacy Policy","example":"123e4567-e89b-12d3-a456-426614174000"}},"required":["hasAcceptedPrivacyPolicy","hasAcceptedLatestVersion","acceptedVersion","privacyPolicyAcceptedAt","latestVersion","latestPrivacyPolicyId"]},"CreatePrivacyPolicyDto":{"type":"object","properties":{"title":{"type":"string","description":"The title of the Privacy Policy","example":"Privacy Policy","maxLength":255},"content":{"type":"string","description":"The full content of the Privacy Policy","example":"This is the full text of the Privacy Policy..."}},"required":["title","content"]},"UpdatePrivacyPolicyDto":{"type":"object","properties":{"title":{"type":"string","description":"The title of the Privacy Policy","example":"Privacy Policy","maxLength":255},"content":{"type":"string","description":"The full content of the Privacy Policy","example":"This is the updated full text of the Privacy Policy..."}}},"CreateHelixgramPostDto":{"type":"object","properties":{}},"CreateHelixgramStoryDto":{"type":"object","properties":{}},"CreateHelixgramReportDto":{"type":"object","properties":{}},"UpdateHelixgramReportStatusDto":{"type":"object","properties":{}},"CreateHelixgramCommentDto":{"type":"object","properties":{}},"NotificationResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the notification"},"userId":{"type":"string","description":"The user ID this notification belongs to"},"type":{"type":"string","description":"The type of notification","enum":["collectible_offer","collectible_sale","server_moderation","phone"]},"status":{"type":"string","description":"The status of the notification","enum":["UNREAD","READ"]},"title":{"type":"string","description":"The title of the notification"},"message":{"type":"string","description":"The message content of the notification"},"payload":{"type":"object","description":"Additional payload data for the notification","nullable":true,"additionalProperties":true},"source":{"type":"string","description":"Which surface a notification originates from. `phone` = an hOS (HELIX phone/tablet) app notification; `central` = a platform notification (commerce, moderation). Both surfaces render the union, so this is a tag for grouping/filtering — not a per-surface filter.","enum":["central","phone"]},"category":{"type":"string","description":"Coarse category for grouping across surfaces: commerce, moderation, social, message, or app-push.","enum":["commerce","moderation","social","message","app-push"]},"readAt":{"type":"object","description":"The date and time when the notification was read","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"The date and time when the notification was created"},"updatedAt":{"format":"date-time","type":"string","description":"The date and time when the notification was last updated"}},"required":["id","userId","type","status","title","message","payload","source","category","readAt","createdAt","updatedAt"]},"UnreadCountResponseDto":{"type":"object","properties":{"count":{"type":"number","description":"The number of unread notifications"}},"required":["count"]},"NotificationPreferenceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the preference"},"userId":{"type":"string","description":"The user ID this preference belongs to"},"notificationType":{"type":"string","description":"The type of notification","enum":["collectible_offer","collectible_sale","server_moderation","phone"]},"inAppEnabled":{"type":"boolean","description":"Whether in-app notifications are enabled"},"emailEnabled":{"type":"boolean","description":"Whether email notifications are enabled"},"createdAt":{"format":"date-time","type":"string","description":"The date and time when the preference was created"},"updatedAt":{"format":"date-time","type":"string","description":"The date and time when the preference was last updated"}},"required":["id","userId","notificationType","inAppEnabled","emailEnabled","createdAt","updatedAt"]},"UpdateNotificationPreferenceDto":{"type":"object","properties":{"notificationType":{"type":"string","description":"The type of notification to update preferences for","enum":["collectible_offer","collectible_sale","server_moderation","phone"]},"inAppEnabled":{"type":"boolean","description":"Whether in-app notifications are enabled"},"emailEnabled":{"type":"boolean","description":"Whether email notifications are enabled"}},"required":["notificationType","inAppEnabled","emailEnabled"]},"InfoResponseDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the OAuth2 application.","example":"My App","nullable":false},"icon":{"type":"object","description":"Icon of the OAuth2 application.","example":"abc.png","nullable":true},"id":{"type":"string","description":"Client ID of the OAuth2 application.","example":"com.example.app","nullable":false},"verified":{"type":"boolean","description":"Whether the OAuth2 application is verified.","example":true,"nullable":false}},"required":["name","icon","id","verified"]},"AuthorizeRequestDto":{"type":"object","properties":{"clientId":{"type":"string","description":"OAuth2 client ID.","example":"com.example.app"},"redirectUri":{"type":"string","description":"OAuth2 redirect URI.","example":"http://localhost:3000/auth/callback"},"scope":{"description":"OAuth2 scope requested.","example":["identify","email","profile"],"type":"array","items":{"type":"string"}},"responseType":{"type":"string","description":"OAuth2 response type.","example":"code"}},"required":["clientId","redirectUri","scope","responseType"]},"AuthorizeResponseDto":{"type":"object","properties":{"code":{"type":"string","description":"Authorization code for the OAuth2 flow.","example":"123abc"}},"required":["code"]},"TokenRequestFormDto":{"type":"object","properties":{"grant_type":{"type":"string","description":"Grant type, must be \"authorization_code\".","example":"authorization_code"},"code":{"type":"string","description":"The authorization code received from the redirect.","example":"abc123"},"redirect_uri":{"type":"string","description":"The same redirect URI that was used in the authorization request.","example":"http://localhost:3000/callback"}},"required":["grant_type","code","redirect_uri"]},"TokenResponseDto":{"type":"object","properties":{"access_token":{"type":"string","description":"User access token.","example":"123abc"},"token_type":{"type":"string","description":"Token type, typically \"Bearer\".","example":"Bearer"},"expires_in":{"type":"number","description":"Token expiration time in seconds.","example":86400},"refresh_token":{"type":"string","description":"Refresh token - currently empty string.","example":"abc123"},"scope":{"type":"string","description":"Scope of the access token, as a space-delimited string.","example":"read write"}},"required":["access_token","token_type","expires_in","refresh_token","scope"]},"OidcUserInfoResponseDto":{"type":"object","properties":{"sub":{"type":"string","description":"The user account ID.","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"The display name of the user.","example":"John Doe"},"preferred_username":{"type":"string","description":"The preferred username of the user.","example":"johndoe"},"email":{"type":"string","description":"The email address of the user.","example":"john.doe@example.com"},"email_verified":{"type":"boolean","description":"Whether the email has been verified.","example":true}},"required":["sub","name","preferred_username"]},"LoginRequestDto":{"type":"object","properties":{"email":{"type":"string","description":"The email of the user.","example":"test@example.com"},"password":{"type":"string","description":"The password of the user.","example":"password"}},"required":["email","password"]},"LoginResponseDto":{"type":"object","properties":{"access_token":{"type":"string","description":"The access token of the user.","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30"},"refresh_token":{"type":"string","description":"The refresh token of the user.","example":"hr_ey..."},"token_type":{"type":"string","description":"The type of the token.","example":"Bearer"},"expires_in":{"type":"number","description":"The expiration time of the access token.","example":3600},"refresh_expires_in":{"type":"number","description":"The expiration time of the refresh token.","example":1209600},"new_user":{"type":"boolean","description":"True when this login created a new passwordless account from an email code.","default":false},"simulation_grant":{"type":"string","description":"Short-lived, revocable grant that reveals the admin simulated-signup option. Admins only."},"simulation_grant_expires_in":{"type":"number","description":"Seconds until the simulation grant expires."}},"required":["access_token","refresh_token","token_type","expires_in","refresh_expires_in"]},"RefreshRequestDto":{"type":"object","properties":{"refresh_token":{"type":"string","description":"The refresh token.","example":"hr_ey..."}},"required":["refresh_token"]},"RefreshResponseDto":{"type":"object","properties":{"access_token":{"type":"string","description":"The new access token of the user.","example":"ey..."},"token_type":{"type":"string","description":"The type of the token.","example":"Bearer"},"expires_in":{"type":"number","description":"The expiration time of the access token.","example":3600}},"required":["access_token","token_type","expires_in"]},"RegisterRequestDto":{"type":"object","properties":{"username":{"type":"string","description":"The username of the user.","example":"exampleuser1","minLength":5,"maxLength":24},"email":{"type":"string","description":"The email of the user.","example":"user@example.com"},"password":{"type":"string","description":"The password of the user.","example":"password123"},"displayName":{"type":"object","description":"The display name of the user.","example":"Conqr","nullable":true,"minLength":2,"maxLength":24},"avatar":{"description":"The avatar image data of the user.","allOf":[{"$ref":"#/components/schemas/ImageRequestDto"}]},"banner":{"description":"The banner image data of the user.","allOf":[{"$ref":"#/components/schemas/ImageRequestDto"}]},"acceptedEulaId":{"type":"string","description":"The UUID of the EULA that the user has accepted during registration. Must be the latest version.","example":"123e4567-e89b-12d3-a456-426614174000"},"acceptedPrivacyPolicyId":{"type":"string","description":"The UUID of the Privacy Policy that the user has accepted during registration. Must be the latest version.","example":"123e4567-e89b-12d3-a456-426614174000"},"acceptedLatestFlag":{"type":"boolean","description":"Flag to automatically accept the latest EULA and Privacy Policy. When true, acceptedEulaId and acceptedPrivacyPolicyId are not required and the latest versions will be used automatically. Still respects ENFORCE_EULA_PRIVACY_POLICY environment variable.","example":true,"default":false},"inviteCode":{"type":"string","description":"The invite code required to register (6-character alphanumeric). Required when ENABLE_INVITE_CODES is true.","example":"ABC123"},"inviteOriginalUrl":{"type":"string"},"inviteDestinationUrl":{"type":"string"},"inviteRedemptionIdempotencyKey":{"type":"string"}},"required":["username","email","password","acceptedEulaId","acceptedPrivacyPolicyId"]},"RequestEmailCodeRequestDto":{"type":"object","properties":{"email":{"type":"string","description":"The email address to send a one-time login code to.","example":"user@example.com"}},"required":["email"]},"RequestEmailCodeResponseDto":{"type":"object","properties":{"challenge_token":{"type":"string","description":"Opaque challenge id to submit with the six-digit code. Carries no code-derived material — the code is verifiable only server-side. Expires quickly."},"expires_in":{"type":"number","description":"Challenge expiration in seconds.","example":600}},"required":["challenge_token","expires_in"]},"VerifyEmailCodeRequestDto":{"type":"object","properties":{"challengeToken":{"type":"string","description":"The signed challenge token returned by /auth/email-code/request."},"code":{"type":"string","description":"The six-digit code sent to the user email address.","example":"123456"},"username":{"type":"string","description":"Required only when the verified email does not already have an account.","example":"exampleuser1"},"inviteCode":{"type":"string"},"inviteOriginalUrl":{"type":"string"},"inviteDestinationUrl":{"type":"string"},"inviteRedemptionIdempotencyKey":{"type":"string"},"acceptedEulaId":{"type":"string"},"acceptedPrivacyPolicyId":{"type":"string"},"acceptedLatestFlag":{"type":"boolean","description":"When true, the backend records acceptance of the latest EULA and Privacy Policy.","default":true}},"required":["challengeToken","code"]},"RequestPasswordResetRequestDto":{"type":"object","properties":{"email":{"type":"string","description":"The email of the user.","example":"test@example.com"},"username":{"type":"string","description":"The username of the user.","example":"exampleuser1"}}},"ResetPasswordRequestDto":{"type":"object","properties":{"token":{"type":"string","description":"The password reset token of the user.","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30"},"password":{"type":"string","description":"The new password of the user.","example":"password"}},"required":["token","password"]},"VerifyPasswordResetTokenRequestDto":{"type":"object","properties":{"token":{"type":"string","description":"The password reset token of the user.","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30"}},"required":["token"]},"RequestEmailVerifyRequestDto":{"type":"object","properties":{"email":{"type":"string","description":"The email of the user.","example":"test@example.com"}},"required":["email"]},"VerifyEmailRequestDto":{"type":"object","properties":{"token":{"type":"string","description":"The email verification token of the user.","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30"}},"required":["token"]},"SetBalancesRequestDto":{"type":"object","properties":{"lix":{"type":"number","description":"Target LIX total (mode=set) or signed LIX delta (mode=delta). Decreases are not supported by the economy microservice and are no-ops with a note.","example":500},"mode":{"type":"string","enum":["set","delta"],"default":"set","description":"\"set\" (default) adjusts to the target value; \"delta\" adds the signed amount to the current balance."}}},"InvitePreviewResponseDto":{"type":"object","properties":{"inviteCode":{"type":"string","example":"ABC123"},"eligible":{"type":"boolean","example":true},"status":{"type":"string","example":"active"},"inviterUsername":{"type":"object","example":"testcreator","nullable":true},"inviterDisplayName":{"type":"object","example":"Test Creator","nullable":true},"inviterAvatarUrl":{"type":"object","nullable":true},"denyReason":{"type":"object","nullable":true}},"required":["inviteCode","eligible","status","inviterUsername","inviterDisplayName","inviterAvatarUrl","denyReason"]},"GrantInviteQuotaResponseDto":{"type":"object","properties":{"userId":{"type":"string","description":"User ID","example":"123e4567-e89b-12d3-a456-426614174000"},"inviteCodesQuota":{"type":"number","description":"Updated invite codes quota","example":10},"inviteCodesCreated":{"type":"number","description":"Number of invite codes already created by this user","example":3},"inviteCodesRemaining":{"type":"number","description":"Remaining invite codes available to create","example":7}},"required":["userId","inviteCodesQuota","inviteCodesCreated","inviteCodesRemaining"]},"GrantInviteQuotaRequestDto":{"type":"object","properties":{"userId":{"type":"string","description":"User ID to grant invite quota to","example":"123e4567-e89b-12d3-a456-426614174000"},"additionalQuota":{"type":"number","description":"Number of additional invite codes to grant","example":5,"minimum":1}},"required":["userId","additionalQuota"]},"UpdateUserInviteSettingsResponseDto":{"type":"object","properties":{"userId":{"type":"string","description":"The UUID of the user","example":"123e4567-e89b-12d3-a456-426614174000"},"inviteCodesQuota":{"type":"number","description":"Updated invite codes quota for the user","example":10},"allowedToGenerateInviteCode":{"type":"boolean","description":"Whether the user is allowed to generate invite codes","example":true},"username":{"type":"string","description":"Username of the user","example":"john_doe"}},"required":["userId","inviteCodesQuota","allowedToGenerateInviteCode","username"]},"UpdateUserInviteSettingsRequestDto":{"type":"object","properties":{"userId":{"type":"string","description":"The UUID of the user to update invite settings for","example":"123e4567-e89b-12d3-a456-426614174000"},"adjustQuotaBy":{"type":"number","description":"Number to add to the user invite codes quota (can be negative to reduce)","example":5},"allowedToGenerateInviteCode":{"type":"boolean","description":"Whether the user is allowed to generate invite codes","example":true}},"required":["userId"]},"InviteResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Invite ID","example":"123e4567-e89b-12d3-a456-426614174000"},"inviteCode":{"type":"string","description":"Invite code (6-character alphanumeric)","example":"ABC123"},"creatorId":{"type":"string","description":"ID of user who created the invite","example":"123e4567-e89b-12d3-a456-426614174000"},"creator":{"description":"User who created the invite","nullable":true,"allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]},"redeemedByUserId":{"type":"object","description":"ID of user who redeemed the invite","example":"123e4567-e89b-12d3-a456-426614174000","nullable":true},"redeemedByUser":{"description":"User who redeemed the invite","nullable":true,"allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]},"redeemedAt":{"type":"object","description":"Timestamp when invite was redeemed","example":"2025-11-13T10:30:00Z","nullable":true},"canBeRedeemed":{"type":"boolean","description":"Whether the invite can be redeemed","example":true},"status":{"type":"string","description":"Invite status","example":"active"},"disabledAt":{"type":"object","description":"Timestamp when invite was disabled","nullable":true},"disabledReason":{"type":"object","description":"Reason the invite was disabled","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when invite was created","example":"2025-11-13T10:00:00Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when invite was last updated","example":"2025-11-13T10:00:00Z"}},"required":["id","inviteCode","creatorId","creator","redeemedByUserId","redeemedByUser","redeemedAt","canBeRedeemed","status","disabledAt","disabledReason","createdAt","updatedAt"]},"UpdateInviteCodeRequestDto":{"type":"object","properties":{"canBeRedeemed":{"type":"boolean","description":"Whether the invite code can be redeemed","example":false}},"required":["canBeRedeemed"]},"InviteRewardGrantResponseDto":{"type":"object","properties":{"id":{"type":"string"},"redemptionId":{"type":"string"},"beneficiaryUserId":{"type":"string"},"role":{"type":"string","example":"invitee"},"amount":{"type":"string","example":"500.0000"},"classification":{"type":"string","example":"promo_non_cashable"},"status":{"type":"string","example":"granted"},"economyIdempotencyKey":{"type":"string"},"economyTransactionId":{"type":"object","nullable":true},"grantedAt":{"type":"object","nullable":true},"failureReason":{"type":"object","nullable":true}},"required":["id","redemptionId","beneficiaryUserId","role","amount","classification","status","economyIdempotencyKey","economyTransactionId","grantedAt","failureReason"]},"InviteRedemptionResponseDto":{"type":"object","properties":{"id":{"type":"string"},"inviteCode":{"type":"string","example":"ABC123"},"inviterUserId":{"type":"string"},"inviteeUserId":{"type":"object","nullable":true},"inviteeUsername":{"type":"object","nullable":true,"example":"newplayer","description":"Username of the account that signed up with this invite. Null when the account is gone — never a placeholder."},"inviteeDisplayName":{"type":"object","nullable":true,"example":"New Player"},"inviteeAvatarUrl":{"type":"object","nullable":true},"originalUrl":{"type":"object","nullable":true},"destinationUrl":{"type":"object","nullable":true},"status":{"type":"string","example":"rewarded"},"acceptedAt":{"type":"object","nullable":true},"rejectedAt":{"type":"object","nullable":true},"rewardedAt":{"type":"object","nullable":true},"denyReason":{"type":"object","nullable":true},"rewardReason":{"type":"object","nullable":true},"idempotencyKey":{"type":"string"},"eligibilityState":{"type":"string","enum":["signed_up","pending_eligibility","earned","reward_failed","reward_capped","not_eligible"],"example":"pending_eligibility","description":"Referral state machine the inviter timeline renders: signed_up → pending_eligibility → earned (or not_eligible / reward_failed)."},"eligibilityRule":{"type":"string","example":"onboarding_quest_completed","description":"The rule that must clear before this referral pays out."},"inviterRewardLix":{"type":"number","example":100,"description":"LIX the inviter earns (or has earned) from this referral."},"inviteeRewardLix":{"type":"number","example":100,"description":"LIX the invitee earns (or has earned) from this referral."},"rewardGrants":{"type":"array","items":{"$ref":"#/components/schemas/InviteRewardGrantResponseDto"}},"createdAt":{"format":"date-time","type":"string"}},"required":["id","inviteCode","inviterUserId","inviteeUserId","inviteeUsername","inviteeDisplayName","inviteeAvatarUrl","originalUrl","destinationUrl","status","acceptedAt","rejectedAt","rewardedAt","denyReason","rewardReason","idempotencyKey","eligibilityState","eligibilityRule","inviterRewardLix","inviteeRewardLix","rewardGrants","createdAt"]},"InviteDashboardResponseDto":{"type":"object","properties":{"inviteId":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"inviteCode":{"type":"string","example":"ABC123"},"status":{"type":"string","example":"active"},"canBeRedeemed":{"type":"boolean","example":true},"acceptedCount":{"type":"number","example":12},"rewardedCount":{"type":"number","example":10},"rejectedCount":{"type":"number","example":2},"inviterRewardLix":{"type":"number","example":1000},"pendingEligibilityCount":{"type":"number","example":2,"description":"Referrals that signed up but have not cleared eligibility yet."},"rewardPerReferralLix":{"type":"number","example":100,"description":"LIX the inviter earns per referral once eligibility clears."},"inviteeRewardLix":{"type":"number","example":100,"description":"LIX the invited player earns once eligibility clears."},"eligibilityRule":{"type":"string","example":"onboarding_quest_completed","description":"The rule a referral must clear before either side is paid."},"rewardedReferralCap":{"type":"number","example":3,"description":"How many referrals this inviter can be PAID for in total. The link itself is unlimited."},"rewardedReferralsRemaining":{"type":"number","example":1,"description":"Rewarded referrals remaining before the inviter payout cap."}},"required":["inviteId","inviteCode","status","canBeRedeemed","acceptedCount","rewardedCount","rejectedCount","inviterRewardLix","pendingEligibilityCount","rewardPerReferralLix","inviteeRewardLix","eligibilityRule","rewardedReferralCap","rewardedReferralsRemaining"]},"AcceptInviteRequestDto":{"type":"object","properties":{"inviteCode":{"type":"string","example":"ABC123"},"originalUrl":{"type":"string"},"destinationUrl":{"type":"string"},"idempotencyKey":{"type":"string","description":"Client-supplied idempotency key. If omitted, the backend derives one from invitee and invite code."}},"required":["inviteCode"]},"CaptureAnalyticsEventDto":{"type":"object","properties":{"event_name":{"type":"string","enum":["user_signed_up","user_logged_in","anonymous_user_identified","invite_sent","invite_link_copied","invite_landed","invite_modal_viewed","invite_opened","invite_accepted","invite_signup_started","invite_signup_completed","invite_reward_granted","invite_reward_denied","referral_source_captured","ftue_started","ftue_step_started","ftue_step_viewed","ftue_step_completed","ftue_step_skipped","ftue_deep_link_destination_entered","ftue_tablet_opened","ftue_hud_minimized","ftue_hud_expanded","ftue_hud_dismissed","ftue_welcome_notification_sent","ftue_reward_claimed","ftue_item_placed","ftue_showcase_home_visited","ftue_item_scanned","ftue_world_joined","ftue_world_objective_completed","ftue_friend_edge_created","ftue_invite_link_copied","ftue_currencies_learned","ftue_item_purchased","ftue_first_post","ftue_creation_published","ftue_completed","ftue_abandoned","session_started","session_ended","world_entered","world_loaded","world_load_failed","world_exited","world_heartbeat","instance_joined","instance_left","friend_request_sent","friend_request_accepted","party_created","party_joined","share_clicked","item_viewed","item_purchased","item_equipped","home_visited","creator_product_viewed","creator_product_purchased","creator_earned","lix_spent","coins_spent","report_submitted","moderation_action_created","content_rating_changed","trust_state_changed","client_error_seen","api_error_seen","developer_publish_cta_clicked","developer_publish_modal_viewed","developer_publish_path_selected","developer_install_command_copied","developer_publish_prompt_copied"]},"event_id":{"type":"string","description":"Client-generated idempotency key for this event.","maxLength":128},"occurred_at":{"type":"string","description":"ISO timestamp for when the event occurred."},"user_id":{"type":"string","description":"Accepted only when a valid bearer token is also supplied; otherwise anonymous_id must identify the actor."},"anonymous_id":{"type":"string"},"session_id":{"type":"string"},"platform":{"type":"string","enum":["web","mobile_webview","ios","android","unreal","server"]},"client_version":{"type":"string"},"source":{"type":"string","enum":["client","server","worker","admin"]},"world_id":{"type":"string"},"instance_id":{"type":"string"},"creator_id":{"type":"string"},"home_id":{"type":"string"},"item_id":{"type":"string"},"invite_id":{"type":"string"},"referrer":{"type":"string"},"properties":{"type":"object","description":"Event-specific JSON metadata. Raw chat, payment details, tokens, secrets, and private messages are rejected."}},"required":["event_name","event_id","occurred_at","platform","source"]},"AnalyticsCaptureResponseDto":{"type":"object","properties":{"accepted":{"type":"number"},"duplicates":{"type":"number"}},"required":["accepted","duplicates"]},"CaptureAnalyticsBatchDto":{"type":"object","properties":{"events":{"maxItems":100,"type":"array","items":{"$ref":"#/components/schemas/CaptureAnalyticsEventDto"}}},"required":["events"]},"StaffAnalyticsJourneySummaryDto":{"type":"object","properties":{"lastSeenAt":{"type":"object","nullable":true},"totalPlaytimeSeconds":{"type":"number"},"averageSessionSeconds":{"type":"number"},"sessionCount":{"type":"number"},"worldCount":{"type":"number"},"inviteSentCount":{"type":"number"},"inviteAcceptedCount":{"type":"number"},"purchaseCount":{"type":"number"},"lixSpent":{"type":"number"}},"required":["lastSeenAt","totalPlaytimeSeconds","averageSessionSeconds","sessionCount","worldCount","inviteSentCount","inviteAcceptedCount","purchaseCount","lixSpent"]},"StaffAnalyticsSessionDto":{"type":"object","properties":{"sessionId":{"type":"string"},"startedAt":{"type":"string"},"lastSeenAt":{"type":"string"},"eventCount":{"type":"number"},"playtimeSeconds":{"type":"number"},"worlds":{"type":"array","items":{"type":"string"}}},"required":["sessionId","startedAt","lastSeenAt","eventCount","playtimeSeconds","worlds"]},"AnalyticsEventDto":{"type":"object","properties":{"id":{"type":"string"},"eventId":{"type":"string"},"eventName":{"type":"string","enum":["user_signed_up","user_logged_in","anonymous_user_identified","invite_sent","invite_link_copied","invite_landed","invite_modal_viewed","invite_opened","invite_accepted","invite_signup_started","invite_signup_completed","invite_reward_granted","invite_reward_denied","referral_source_captured","ftue_started","ftue_step_started","ftue_step_viewed","ftue_step_completed","ftue_step_skipped","ftue_deep_link_destination_entered","ftue_tablet_opened","ftue_hud_minimized","ftue_hud_expanded","ftue_hud_dismissed","ftue_welcome_notification_sent","ftue_reward_claimed","ftue_item_placed","ftue_showcase_home_visited","ftue_item_scanned","ftue_world_joined","ftue_world_objective_completed","ftue_friend_edge_created","ftue_invite_link_copied","ftue_currencies_learned","ftue_item_purchased","ftue_first_post","ftue_creation_published","ftue_completed","ftue_abandoned","session_started","session_ended","world_entered","world_loaded","world_load_failed","world_exited","world_heartbeat","instance_joined","instance_left","friend_request_sent","friend_request_accepted","party_created","party_joined","share_clicked","item_viewed","item_purchased","item_equipped","home_visited","creator_product_viewed","creator_product_purchased","creator_earned","lix_spent","coins_spent","report_submitted","moderation_action_created","content_rating_changed","trust_state_changed","client_error_seen","api_error_seen","developer_publish_cta_clicked","developer_publish_modal_viewed","developer_publish_path_selected","developer_install_command_copied","developer_publish_prompt_copied"]},"occurredAt":{"format":"date-time","type":"string"},"receivedAt":{"format":"date-time","type":"string"},"userId":{"type":"object","nullable":true},"anonymousId":{"type":"object","nullable":true},"sessionId":{"type":"object","nullable":true},"platform":{"type":"string","enum":["web","mobile_webview","ios","android","unreal","server"]},"source":{"type":"string","enum":["client","server","worker","admin"]},"worldId":{"type":"object","nullable":true},"creatorId":{"type":"object","nullable":true},"itemId":{"type":"object","nullable":true},"inviteId":{"type":"object","nullable":true},"actorType":{"type":"object","nullable":true},"actorId":{"type":"object","nullable":true},"actorKey":{"type":"object","nullable":true},"actorLabel":{"type":"object","nullable":true},"worldLabel":{"type":"object","nullable":true},"worldDetailPath":{"type":"object","nullable":true},"properties":{"type":"object"}},"required":["id","eventId","eventName","occurredAt","receivedAt","userId","anonymousId","sessionId","platform","source","worldId","creatorId","itemId","inviteId","actorType","actorId","actorKey","actorLabel","worldLabel","worldDetailPath","properties"]},"StaffAnalyticsJourneyResponseDto":{"type":"object","properties":{"summary":{"$ref":"#/components/schemas/StaffAnalyticsJourneySummaryDto"},"sessions":{"type":"array","items":{"$ref":"#/components/schemas/StaffAnalyticsSessionDto"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsEventDto"}}},"required":["summary","sessions","events"]},"AnalyticsFunnelStepDto":{"type":"object","properties":{"eventName":{"type":"string","enum":["user_signed_up","user_logged_in","anonymous_user_identified","invite_sent","invite_link_copied","invite_landed","invite_modal_viewed","invite_opened","invite_accepted","invite_signup_started","invite_signup_completed","invite_reward_granted","invite_reward_denied","referral_source_captured","ftue_started","ftue_step_started","ftue_step_viewed","ftue_step_completed","ftue_step_skipped","ftue_deep_link_destination_entered","ftue_tablet_opened","ftue_hud_minimized","ftue_hud_expanded","ftue_hud_dismissed","ftue_welcome_notification_sent","ftue_reward_claimed","ftue_item_placed","ftue_showcase_home_visited","ftue_item_scanned","ftue_world_joined","ftue_world_objective_completed","ftue_friend_edge_created","ftue_invite_link_copied","ftue_currencies_learned","ftue_item_purchased","ftue_first_post","ftue_creation_published","ftue_completed","ftue_abandoned","session_started","session_ended","world_entered","world_loaded","world_load_failed","world_exited","world_heartbeat","instance_joined","instance_left","friend_request_sent","friend_request_accepted","party_created","party_joined","share_clicked","item_viewed","item_purchased","item_equipped","home_visited","creator_product_viewed","creator_product_purchased","creator_earned","lix_spent","coins_spent","report_submitted","moderation_action_created","content_rating_changed","trust_state_changed","client_error_seen","api_error_seen","developer_publish_cta_clicked","developer_publish_modal_viewed","developer_publish_path_selected","developer_install_command_copied","developer_publish_prompt_copied"]},"actors":{"type":"number"},"events":{"type":"number"},"conversionFromPrevious":{"type":"object"}},"required":["eventName","actors","events","conversionFromPrevious"]},"AnalyticsFunnelResponseDto":{"type":"object","properties":{"funnel":{"type":"string"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsFunnelStepDto"}}},"required":["funnel","steps"]},"AnalyticsExportResponseDto":{"type":"object","properties":{"generatedAt":{"type":"string"},"redacted":{"type":"boolean"},"events":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsEventDto"}}},"required":["generatedAt","redacted","events"]},"AnalyticsActorWorldSummaryDto":{"type":"object","properties":{"worldId":{"type":"string"},"worldLabel":{"type":"object","nullable":true},"worldDetailPath":{"type":"object","nullable":true},"events":{"type":"number"},"playtimeSeconds":{"type":"number"}},"required":["worldId","worldLabel","worldDetailPath","events","playtimeSeconds"]},"AnalyticsActorSummaryDto":{"type":"object","properties":{"actorType":{"type":"string"},"actorId":{"type":"string"},"actorKey":{"type":"string"},"actorLabel":{"type":"string"},"lastSeenAt":{"type":"object","nullable":true},"eventCount":{"type":"number"},"sessionCount":{"type":"number"},"totalPlaytimeSeconds":{"type":"number"},"averageSessionSeconds":{"type":"number"},"topWorlds":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsActorWorldSummaryDto"}}},"required":["actorType","actorId","actorKey","actorLabel","lastSeenAt","eventCount","sessionCount","totalPlaytimeSeconds","averageSessionSeconds","topWorlds"]},"AnalyticsActorDetailResponseDto":{"type":"object","properties":{"actor":{"$ref":"#/components/schemas/AnalyticsActorSummaryDto"},"sessions":{"type":"array","items":{"$ref":"#/components/schemas/StaffAnalyticsSessionDto"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsEventDto"}}},"required":["actor","sessions","events"]},"AnalyticsInsightJobScaffoldDto":{"type":"object","properties":{"job":{"type":"string"},"inputs":{"type":"array","items":{"type":"string"}},"guardrails":{"type":"array","items":{"type":"string"}},"suggestedOutputs":{"type":"array","items":{"type":"string"}}},"required":["job","inputs","guardrails","suggestedOutputs"]},"CreatorAnalyticsRollupPointDto":{"type":"object","properties":{"bucket":{"type":"string"},"visits":{"type":"number"},"uniqueVisitors":{"type":"number"},"totalPlaytimeSeconds":{"type":"number"},"averageSessionSeconds":{"type":"number"},"purchases":{"type":"number"},"earningsEvents":{"type":"number"}},"required":["bucket","visits","uniqueVisitors","totalPlaytimeSeconds","averageSessionSeconds","purchases","earningsEvents"]},"CreatorAnalyticsRollupWorldDto":{"type":"object","properties":{"worldId":{"type":"string"},"worldLabel":{"type":"object","nullable":true},"worldDetailPath":{"type":"object","nullable":true},"visits":{"type":"number"},"uniqueVisitors":{"type":"number"}},"required":["worldId","worldLabel","worldDetailPath","visits","uniqueVisitors"]},"CreatorAnalyticsRollupResponseDto":{"type":"object","properties":{"grain":{"type":"string","enum":["hour","day"]},"worldId":{"type":"object","nullable":true},"homeId":{"type":"object","nullable":true,"description":"Set only for a per-home rollup. Home rollups report visits/visitors only; `worlds` is always empty."},"creatorId":{"type":"string"},"visits":{"type":"number"},"uniqueVisitors":{"type":"number"},"newVisitors":{"type":"number"},"returningVisitors":{"type":"number"},"totalPlaytimeSeconds":{"type":"number"},"averageSessionSeconds":{"type":"number"},"purchases":{"type":"number"},"earningsEvents":{"type":"number"},"inviteReferrers":{"type":"object"},"topItems":{"type":"array","items":{"type":"string"}},"dropoff":{"type":"array","items":{"type":"string"}},"trend":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsRollupPointDto"}},"worlds":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsRollupWorldDto"}},"truncated":{"type":"boolean","description":"True when the raw-event scan backing this rollup hit its row cap, so the metrics are computed over a truncated window and UNDERCOUNT. A durable daily-rollup table (planned) removes this ceiling; until then the client should surface an \"approximate\" badge and narrow the date range."}},"required":["grain","worldId","homeId","creatorId","visits","uniqueVisitors","newVisitors","returningVisitors","totalPlaytimeSeconds","averageSessionSeconds","purchases","earningsEvents","inviteReferrers","topItems","dropoff","trend","worlds","truncated"]},"SteamKeyResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Steam Key ID","example":"123e4567-e89b-12d3-a456-426614174000"},"key":{"type":"string","description":"Steam key value","example":"XXXXX-XXXXX-XXXXX"},"userId":{"type":"object","description":"ID of user who has claimed this key","example":"123e4567-e89b-12d3-a456-426614174000","nullable":true},"user":{"description":"User who has claimed this key","nullable":true,"allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]},"assignedAt":{"type":"object","description":"Timestamp when key was assigned to a user","example":"2025-12-09T10:30:00Z","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when key was created","example":"2025-12-09T10:00:00Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when key was last updated","example":"2025-12-09T10:00:00Z"}},"required":["id","key","userId","user","assignedAt","createdAt","updatedAt"]},"CreateSteamKeyRequestDto":{"type":"object","properties":{"key":{"type":"string","description":"The Steam key value","example":"XXXXX-XXXXX-XXXXX","maxLength":255}},"required":["key"]},"BulkCreateSteamKeysRequestDto":{"type":"object","properties":{"keys":{"description":"Array of Steam key values to create","example":["XXXXX-XXXXX-XXXXX","YYYYY-YYYYY-YYYYY"],"type":"array","items":{"type":"string"}}},"required":["keys"]},"UpdateSteamKeyRequestDto":{"type":"object","properties":{"userId":{"type":"object","description":"User ID to assign this key to (or null to unassign)","example":"123e4567-e89b-12d3-a456-426614174000","nullable":true}}},"PatchkitKeyResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Patchkit Key ID","example":"123e4567-e89b-12d3-a456-426614174000"},"key":{"type":"string","description":"Patchkit key value","example":"XXXXX-XXXXX-XXXXX"},"userId":{"type":"object","description":"ID of user who has claimed this key","example":"123e4567-e89b-12d3-a456-426614174000","nullable":true},"user":{"description":"User who has claimed this key","nullable":true,"allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]},"assignedAt":{"type":"object","description":"Timestamp when key was assigned to a user","example":"2025-12-09T10:30:00Z","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when key was created","example":"2025-12-09T10:00:00Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when key was last updated","example":"2025-12-09T10:00:00Z"}},"required":["id","key","userId","user","assignedAt","createdAt","updatedAt"]},"ClaimPatchkitKeyRequestDto":{"type":"object","properties":{"key":{"type":"string","description":"The Patchkit key to claim","example":"XXXXX-XXXXX-XXXXX","maxLength":255}},"required":["key"]},"CreatePatchkitKeyRequestDto":{"type":"object","properties":{"key":{"type":"string","description":"The Patchkit key value","example":"XXXXX-XXXXX-XXXXX","maxLength":255}},"required":["key"]},"BulkCreatePatchkitKeysRequestDto":{"type":"object","properties":{"keys":{"description":"Array of Patchkit key values to create","example":["XXXXX-XXXXX-XXXXX","YYYYY-YYYYY-YYYYY"],"type":"array","items":{"type":"string"}}},"required":["keys"]},"UpdatePatchkitKeyRequestDto":{"type":"object","properties":{"userId":{"type":"object","description":"User ID to assign this key to (or null to unassign)","example":"123e4567-e89b-12d3-a456-426614174000","nullable":true}}},"CreateServerResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the server.","example":"da1c4709-9723-4df5-9587-1cabb675611c"},"ownerId":{"type":"string","description":"The ID of the owner of the server.","example":"6fdbdb34-bd55-4d7b-8094-c72e9e0a4fa4"},"slug":{"type":"string","description":"The slug of the server.","example":"my-server"},"name":{"type":"string","description":"The name of the server.","example":"My Server"},"description":{"type":"string","description":"The description of the server.","example":"This is a description of my server."},"tags":{"description":"The tags of the server.","example":["Sandbox","Roleplay","PvP"],"type":"array","items":{"type":"string"}},"contentRating":{"type":"string","description":"The content rating of the server.","example":"Everyone"},"contentRatingStatus":{"type":"string","description":"The trust-and-safety review status of the content rating.","example":"pending_review"},"contentRatingDeclaredAt":{"type":"object","nullable":true},"contentRatingReviewedAt":{"type":"object","nullable":true},"gameMode":{"type":"string","description":"The game mode of the server.","example":"Sandbox"},"hostingType":{"type":"string","description":"The hosting type of the server.","example":"Dedicated"},"gameVersion":{"type":"string","description":"The game version of the server.","example":"1.0.0"},"worldId":{"type":"string","description":"The world ID of the server.","example":"e4412457-5bd4-44e2-a219-80fd3944d378"},"ipAddress":{"type":"string","description":"The IP address of the server.","example":"127.0.0.1"},"port":{"type":"number","description":"The port of the server.","example":7777},"currentPlayers":{"type":"number","description":"The current number of players on the server.","example":10},"maxPlayers":{"type":"number","description":"The maximum number of players on the server.","example":64},"playerIds":{"description":"The IDs of the players on the server.","example":["9669d149-349e-4bca-a58a-c8e1614bbc63","f3735be6-0ebc-4007-a9c7-1fe1ad0884b6","4b7bc58d-5906-404f-82a6-0c1f52d489d2"],"type":"array","items":{"type":"string"}},"status":{"type":"string","description":"The status of the server.","example":"Online"},"visits":{"type":"number","description":"The number of visits to the server.","example":12345},"currentRating":{"type":"number","description":"The current rating of the server.","example":4.5},"totalRatings":{"type":"number","description":"The total number of ratings for the server.","example":1337},"previews":{"description":"The previews of the package.","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"region":{"type":"string","description":"The server's region (2-letter ISO code).","example":"US","nullable":true},"heartbeatAddress":{"type":"object","description":"Heartbeat server address (provisioned servers only).","nullable":true},"nucleusIport":{"type":"object","description":"Nucleus internal port (provisioned servers only).","nullable":true},"workspaceId":{"type":"object","description":"Workspace ID (provisioned servers only).","nullable":true},"levelAsset":{"type":"object","description":"Level asset path (provisioned servers only).","nullable":true},"sideloadPaks":{"type":"object","description":"Comma-separated sideload pak files (provisioned servers only).","nullable":true},"systemDependencies":{"type":"object","description":"System dependencies (provisioned servers only).","nullable":true},"isPrivate":{"type":"boolean","description":"Whether the server is private.","example":false},"isFavorited":{"type":"boolean","description":"Whether the current authenticated user has favorited this server.","example":false},"whitelist":{"description":"Users whitelisted to access this private server.","type":"array","items":{"$ref":"#/components/schemas/UserResponseDto"}},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the server was published.","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"The date and time the server was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the server was updated."},"lastTimeOnline":{"format":"date-time","type":"string","description":"The date and time the server was last online (last heartbeat received).","nullable":true},"owner":{"description":"The owner of the server.","allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]},"world":{"description":"The world definition for the server.","allOf":[{"$ref":"#/components/schemas/ServerPackageWithDetailsResponseDto"}]},"secret":{"type":"string","description":"The secret of the server.","example":"qD2hnQmNHPbM0o1dB5jyB9wzg0uz4DIz"},"serverToken":{"type":"string","description":"A server token (JWT refresh-style) valid for 6 months.","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"previewUploadUrls":{"description":"The upload URLs of the server previews.","example":["https://example.com/123e4567-e89b-12d3-a456-426614174000/previews/Preview_1","https://example.com/123e4567-e89b-12d3-a456-426614174000/previews/Preview_2"],"type":"array","items":{"type":"string"}}},"required":["id","ownerId","slug","name","description","tags","contentRating","contentRatingStatus","gameMode","hostingType","gameVersion","worldId","ipAddress","port","currentPlayers","maxPlayers","playerIds","status","visits","currentRating","totalRatings","previews","region","isPrivate","whitelist","publishedAt","createdAt","updatedAt","lastTimeOnline","owner","world","secret","serverToken","previewUploadUrls"]},"CreateServerRequestDto":{"type":"object","properties":{"slug":{"type":"string","description":"The slug of the server.","example":"my-server"},"name":{"type":"string","description":"The name of the server.","example":"My Server"},"description":{"type":"string","description":"The description of the server.","example":"This is a description of my server."},"worldId":{"type":"string","description":"The world ID of the server.","example":"e4412457-5bd4-44e2-a219-80fd3944d378"},"packageVersionIds":{"description":"The IDs of the packages that the server is associated with.","example":["123e4567-e89b-12d3-a456-426614174000","456e7890-e89b-12d3-a456-426614174000"],"default":[],"type":"array","items":{"type":"string"}},"gameVersion":{"type":"string","description":"The game version of the server.","example":"1.0.0","default":"1.0.0"},"tags":{"description":"The tags of the server.","example":["Sandbox","Roleplay","PvP"],"default":["Sandbox"],"type":"array","items":{"type":"string"}},"contentRating":{"type":"string","description":"The content rating of the server.","example":"Everyone","default":"Everyone"},"gameMode":{"type":"string","description":"The game mode of the server.","example":"Sandbox","default":"Sandbox"},"hostingType":{"type":"string","description":"The hosting type of the server.","example":"Dedicated","default":"Local"},"ipAddress":{"type":"string","description":"The IP address of the server.","example":"127.0.0.1","default":"127.0.0.1"},"region":{"type":"string","description":"The server's geographic region (2-letter ISO code).","example":"US"},"port":{"type":"number","description":"The port of the server.","example":7777,"default":7777},"maxPlayers":{"type":"number","description":"The maximum number of players on the server.","example":64,"default":64},"previewKeys":{"description":"An array of keys of the server previews.","example":["Preview_1","Preview_2"],"default":[],"type":"array","items":{"type":"string"}},"isPrivate":{"type":"boolean","description":"Whether the server is private.","example":false,"default":false},"whitelistUserIds":{"description":"List of user IDs that are whitelisted to access this private server.","example":["123e4567-e89b-12d3-a456-426614174000","456e7890-e89b-12d3-a456-426614174000"],"default":[],"type":"array","items":{"type":"string"}},"whitelistUsernames":{"description":"List of usernames that are whitelisted to access this private server. Cannot be used together with whitelistUserIds.","example":["johndoe","janedoe"],"default":[],"type":"array","items":{"type":"string"}},"serverPlanId":{"type":"string","description":"The server plan ID for provisioned hosting. Required when hostingType is Provisioned.","example":"123e4567-e89b-12d3-a456-426614174000"},"provisionedRegion":{"type":"string","description":"The datacenter region for provisioned hosting (e.g. DE1, UK1, BHS5). Required when hostingType is Provisioned.","example":"DE1"},"billingPeriod":{"type":"string","description":"The billing period for provisioned hosting. Required when hostingType is Provisioned.","example":"Monthly","enum":["Monthly"]},"heartbeatAddress":{"type":"string","description":"Heartbeat server address (provisioned servers only).","example":"heartbeat.helix.server"},"nucleusIport":{"type":"string","description":"Nucleus internal port (provisioned servers only).","example":"8080"},"workspaceId":{"type":"string","description":"Workspace ID (provisioned servers only).","example":"my-workspace-id"},"levelAsset":{"type":"string","description":"Level asset path (provisioned servers only).","example":"/Game/Maps/MyLevel"},"sideloadPaks":{"type":"string","description":"Comma-separated sideload pak files (provisioned servers only).","example":"pak1,pak2"},"systemDependencies":{"type":"string","description":"System dependencies (provisioned servers only).","example":"libssl-dev,libcurl4"}},"required":["slug","name","description","worldId"]},"ServerTokenResponseDto":{"type":"object","properties":{"serverToken":{"type":"string","description":"A server token (JWT refresh-style) valid for 6 months.","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIuLi4iLCJ0eXBlIjoicmVmcmVzaCIsImV4cCI6Li4ufQ.sgn"}},"required":["serverToken"]},"UpdateServerResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the server.","example":"da1c4709-9723-4df5-9587-1cabb675611c"},"ownerId":{"type":"string","description":"The ID of the owner of the server.","example":"6fdbdb34-bd55-4d7b-8094-c72e9e0a4fa4"},"slug":{"type":"string","description":"The slug of the server.","example":"my-server"},"name":{"type":"string","description":"The name of the server.","example":"My Server"},"description":{"type":"string","description":"The description of the server.","example":"This is a description of my server."},"tags":{"description":"The tags of the server.","example":["Sandbox","Roleplay","PvP"],"type":"array","items":{"type":"string"}},"contentRating":{"type":"string","description":"The content rating of the server.","example":"Everyone"},"contentRatingStatus":{"type":"string","description":"The trust-and-safety review status of the content rating.","example":"pending_review"},"contentRatingDeclaredAt":{"type":"object","nullable":true},"contentRatingReviewedAt":{"type":"object","nullable":true},"gameMode":{"type":"string","description":"The game mode of the server.","example":"Sandbox"},"hostingType":{"type":"string","description":"The hosting type of the server.","example":"Dedicated"},"gameVersion":{"type":"string","description":"The game version of the server.","example":"1.0.0"},"worldId":{"type":"string","description":"The world ID of the server.","example":"e4412457-5bd4-44e2-a219-80fd3944d378"},"ipAddress":{"type":"string","description":"The IP address of the server.","example":"127.0.0.1"},"port":{"type":"number","description":"The port of the server.","example":7777},"currentPlayers":{"type":"number","description":"The current number of players on the server.","example":10},"maxPlayers":{"type":"number","description":"The maximum number of players on the server.","example":64},"playerIds":{"description":"The IDs of the players on the server.","example":["9669d149-349e-4bca-a58a-c8e1614bbc63","f3735be6-0ebc-4007-a9c7-1fe1ad0884b6","4b7bc58d-5906-404f-82a6-0c1f52d489d2"],"type":"array","items":{"type":"string"}},"status":{"type":"string","description":"The status of the server.","example":"Online"},"visits":{"type":"number","description":"The number of visits to the server.","example":12345},"currentRating":{"type":"number","description":"The current rating of the server.","example":4.5},"totalRatings":{"type":"number","description":"The total number of ratings for the server.","example":1337},"previews":{"description":"The previews of the package.","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"region":{"type":"string","description":"The server's region (2-letter ISO code).","example":"US","nullable":true},"heartbeatAddress":{"type":"object","description":"Heartbeat server address (provisioned servers only).","nullable":true},"nucleusIport":{"type":"object","description":"Nucleus internal port (provisioned servers only).","nullable":true},"workspaceId":{"type":"object","description":"Workspace ID (provisioned servers only).","nullable":true},"levelAsset":{"type":"object","description":"Level asset path (provisioned servers only).","nullable":true},"sideloadPaks":{"type":"object","description":"Comma-separated sideload pak files (provisioned servers only).","nullable":true},"systemDependencies":{"type":"object","description":"System dependencies (provisioned servers only).","nullable":true},"isPrivate":{"type":"boolean","description":"Whether the server is private.","example":false},"isFavorited":{"type":"boolean","description":"Whether the current authenticated user has favorited this server.","example":false},"whitelist":{"description":"Users whitelisted to access this private server.","type":"array","items":{"$ref":"#/components/schemas/UserResponseDto"}},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the server was published.","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"The date and time the server was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the server was updated."},"lastTimeOnline":{"format":"date-time","type":"string","description":"The date and time the server was last online (last heartbeat received).","nullable":true},"owner":{"description":"The owner of the server.","allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]},"world":{"description":"The world definition for the server.","allOf":[{"$ref":"#/components/schemas/ServerPackageWithDetailsResponseDto"}]},"secret":{"type":"string","description":"The secret of the server.","example":"qD2hnQmNHPbM0o1dB5jyB9wzg0uz4DIz"},"previewUploadUrls":{"description":"The upload URLs of the server previews.","example":["https://example.com/123e4567-e89b-12d3-a456-426614174000/previews/Preview_1","https://example.com/123e4567-e89b-12d3-a456-426614174000/previews/Preview_2"],"type":"array","items":{"type":"string"}},"thumbnailUploadUrls":{"description":"The upload URLs of the server thumbnails.","example":["https://example.com/123e4567-e89b-12d3-a456-426614174000/thumbnails/Thumbnail_1","https://example.com/123e4567-e89b-12d3-a456-426614174000/thumbnails/Thumbnail_2"],"type":"array","items":{"type":"string"}}},"required":["id","ownerId","slug","name","description","tags","contentRating","contentRatingStatus","gameMode","hostingType","gameVersion","worldId","ipAddress","port","currentPlayers","maxPlayers","playerIds","status","visits","currentRating","totalRatings","previews","region","isPrivate","whitelist","publishedAt","createdAt","updatedAt","lastTimeOnline","owner","world","secret","previewUploadUrls","thumbnailUploadUrls"]},"UpdateServerRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the server.","example":"My Server"},"description":{"type":"string","description":"The description of the server.","example":"This is a description of my server."},"tags":{"description":"The tags of the server.","example":["Sandbox","Roleplay","PvP"],"type":"array","items":{"type":"string"}},"contentRating":{"type":"string","description":"The content rating of the server.","example":"Everyone"},"gameMode":{"type":"string","description":"The game mode of the server.","example":"Sandbox"},"gameVersion":{"type":"string","description":"The game version of the server.","example":"1.0.0"},"worldId":{"type":"string","description":"The world ID of the server.","example":"e4412457-5bd4-44e2-a219-80fd3944d378"},"ipAddress":{"type":"string","description":"The IP address of the server.","example":"127.0.0.1"},"port":{"type":"number","description":"The port of the server.","example":7777,"minimum":1,"maximum":65535},"maxPlayers":{"type":"number","description":"The maximum number of players on the server.","example":64,"minimum":1,"maximum":64},"previewKeys":{"description":"An array of keys of the server previews.","example":["Preview_1","Preview_2"],"type":"array","items":{"type":"string"}},"thumbnailKeys":{"description":"An array of keys of the server thumbnails.","example":["Thumbnail_1","Thumbnail_2"],"type":"array","items":{"type":"string"}},"region":{"type":"string","description":"The server's region, or null to clear it.","example":"US","nullable":true},"isPrivate":{"type":"boolean","description":"Whether the server is private.","example":false},"whitelistUserIds":{"description":"List of user IDs that are whitelisted to access this private server.","example":["123e4567-e89b-12d3-a456-426614174000","456e7890-e89b-12d3-a456-426614174000"],"type":"array","items":{"type":"string"}},"whitelistUsernames":{"description":"List of usernames that are whitelisted to access this private server. Cannot be used together with whitelistUserIds.","example":["johndoe","janedoe"],"type":"array","items":{"type":"string"}},"heartbeatAddress":{"type":"string","description":"Heartbeat server address (provisioned servers only).","example":"heartbeat.helix.server"},"nucleusIport":{"type":"string","description":"Nucleus internal port (provisioned servers only).","example":"8080"},"workspaceId":{"type":"string","description":"Workspace ID (provisioned servers only).","example":"my-workspace-id"},"levelAsset":{"type":"string","description":"Level asset path (provisioned servers only).","example":"/Game/Maps/MyLevel"},"sideloadPaks":{"type":"string","description":"Comma-separated sideload pak files (provisioned servers only).","example":"pak1,pak2"},"systemDependencies":{"type":"string","description":"System dependencies (provisioned servers only).","example":"libssl-dev,libcurl4"}}},"ModerateUserRequestDto":{"type":"object","properties":{"userId":{"type":"string","description":"User ID to moderate","format":"uuid"},"durationSeconds":{"type":"number","description":"Duration in seconds for ban/kick (defaults to 3600 = 1h)","example":3600},"reason":{"type":"string","description":"Optional reason for the ban or kick","example":"Violation of server rules"}},"required":["userId"]},"UpdateModerationRequestDto":{"type":"object","properties":{"durationSeconds":{"type":"number","description":"New duration in seconds for ban/kick","example":7200},"reason":{"type":"string","description":"New reason for the ban or kick (use empty string to clear)","example":"Updated: Repeated violation of server rules"}}},"ServerWithSecretResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the server.","example":"da1c4709-9723-4df5-9587-1cabb675611c"},"ownerId":{"type":"string","description":"The ID of the owner of the server.","example":"6fdbdb34-bd55-4d7b-8094-c72e9e0a4fa4"},"slug":{"type":"string","description":"The slug of the server.","example":"my-server"},"name":{"type":"string","description":"The name of the server.","example":"My Server"},"description":{"type":"string","description":"The description of the server.","example":"This is a description of my server."},"tags":{"description":"The tags of the server.","example":["Sandbox","Roleplay","PvP"],"type":"array","items":{"type":"string"}},"contentRating":{"type":"string","description":"The content rating of the server.","example":"Everyone"},"contentRatingStatus":{"type":"string","description":"The trust-and-safety review status of the content rating.","example":"pending_review"},"contentRatingDeclaredAt":{"type":"object","nullable":true},"contentRatingReviewedAt":{"type":"object","nullable":true},"gameMode":{"type":"string","description":"The game mode of the server.","example":"Sandbox"},"hostingType":{"type":"string","description":"The hosting type of the server.","example":"Dedicated"},"gameVersion":{"type":"string","description":"The game version of the server.","example":"1.0.0"},"worldId":{"type":"string","description":"The world ID of the server.","example":"e4412457-5bd4-44e2-a219-80fd3944d378"},"ipAddress":{"type":"string","description":"The IP address of the server.","example":"127.0.0.1"},"port":{"type":"number","description":"The port of the server.","example":7777},"currentPlayers":{"type":"number","description":"The current number of players on the server.","example":10},"maxPlayers":{"type":"number","description":"The maximum number of players on the server.","example":64},"playerIds":{"description":"The IDs of the players on the server.","example":["9669d149-349e-4bca-a58a-c8e1614bbc63","f3735be6-0ebc-4007-a9c7-1fe1ad0884b6","4b7bc58d-5906-404f-82a6-0c1f52d489d2"],"type":"array","items":{"type":"string"}},"status":{"type":"string","description":"The status of the server.","example":"Online"},"visits":{"type":"number","description":"The number of visits to the server.","example":12345},"currentRating":{"type":"number","description":"The current rating of the server.","example":4.5},"totalRatings":{"type":"number","description":"The total number of ratings for the server.","example":1337},"previews":{"description":"The previews of the package.","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"region":{"type":"string","description":"The server's region (2-letter ISO code).","example":"US","nullable":true},"heartbeatAddress":{"type":"object","description":"Heartbeat server address (provisioned servers only).","nullable":true},"nucleusIport":{"type":"object","description":"Nucleus internal port (provisioned servers only).","nullable":true},"workspaceId":{"type":"object","description":"Workspace ID (provisioned servers only).","nullable":true},"levelAsset":{"type":"object","description":"Level asset path (provisioned servers only).","nullable":true},"sideloadPaks":{"type":"object","description":"Comma-separated sideload pak files (provisioned servers only).","nullable":true},"systemDependencies":{"type":"object","description":"System dependencies (provisioned servers only).","nullable":true},"isPrivate":{"type":"boolean","description":"Whether the server is private.","example":false},"isFavorited":{"type":"boolean","description":"Whether the current authenticated user has favorited this server.","example":false},"whitelist":{"description":"Users whitelisted to access this private server.","type":"array","items":{"$ref":"#/components/schemas/UserResponseDto"}},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the server was published.","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"The date and time the server was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the server was updated."},"lastTimeOnline":{"format":"date-time","type":"string","description":"The date and time the server was last online (last heartbeat received).","nullable":true},"owner":{"description":"The owner of the server.","allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]},"world":{"description":"The world definition for the server.","allOf":[{"$ref":"#/components/schemas/ServerPackageWithDetailsResponseDto"}]},"secret":{"type":"string","description":"The secret of the server.","example":"qD2hnQmNHPbM0o1dB5jyB9wzg0uz4DIz"}},"required":["id","ownerId","slug","name","description","tags","contentRating","contentRatingStatus","gameMode","hostingType","gameVersion","worldId","ipAddress","port","currentPlayers","maxPlayers","playerIds","status","visits","currentRating","totalRatings","previews","region","isPrivate","whitelist","publishedAt","createdAt","updatedAt","lastTimeOnline","owner","world","secret"]},"TransferServerOwnershipRequestDto":{"type":"object","properties":{"serverIds":{"description":"Array of server IDs to transfer","type":"array","items":{"type":"string"}},"userId":{"type":"string","description":"The target user ID who will become the new owner"}},"required":["serverIds","userId"]},"ServerStatus":{"type":"string","enum":["Offline","Starting","Stopping","Online","Updating","Error"],"description":"The status of the server."},"UpdateServerStatusRequestDto":{"type":"object","properties":{"playerIds":{"description":"The IDs of the players on the server.","example":["dfa3d263-01b8-4dcd-885d-7b97b9e55084","498d404e-8f29-4166-88ca-47aba3f5f302"],"type":"array","items":{"type":"string"}},"ipAddress":{"type":"string","description":"The IP address of the server.","example":"127.0.0.1"},"port":{"type":"number","description":"The port of the server.","example":7777,"minimum":1024,"maximum":65535},"status":{"description":"The status of the server.","example":"Online","allOf":[{"$ref":"#/components/schemas/ServerStatus"}]},"gameVersion":{"type":"string","description":"The game version of the server.","example":"1.0.0"}}},"ServerPermissionGroupResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Permission group ID.","format":"uuid"},"serverId":{"type":"string","description":"Server ID.","format":"uuid"},"name":{"type":"string","description":"Permission group name."},"permissions":{"type":"number","description":"Integer bitflag permissions value."},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp."}},"required":["id","serverId","name","permissions","createdAt"]},"ServerAssignmentUserDto":{"type":"object","properties":{"id":{"type":"string","description":"User ID.","format":"uuid"},"username":{"type":"string","description":"Username."}},"required":["id","username"]},"ServerUserGroupAssignmentResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Assignment ID.","format":"uuid"},"serverId":{"type":"string","description":"Server ID.","format":"uuid"},"userId":{"type":"string","description":"User ID.","format":"uuid"},"user":{"description":"Basic profile of the assigned user (when resolved).","allOf":[{"$ref":"#/components/schemas/ServerAssignmentUserDto"}]},"group":{"description":"Assigned permission group.","allOf":[{"$ref":"#/components/schemas/ServerPermissionGroupResponseDto"}]},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp."}},"required":["id","serverId","userId","group","createdAt"]},"CreateServerPermissionGroupRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable group name for this server.","example":"admin"},"permissions":{"type":"number","description":"Integer bitflag permissions value.","example":31,"minimum":0,"maximum":2147483647}},"required":["name","permissions"]},"UpdateServerPermissionGroupRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable group name for this server.","example":"mod"},"permissions":{"type":"number","description":"Integer bitflag permissions value.","example":7,"minimum":0,"maximum":2147483647}}},"OkResponseDto":{"type":"object","properties":{"ok":{"type":"boolean","example":true}},"required":["ok"]},"AssignServerUserGroupRequestDto":{"type":"object","properties":{"groupId":{"type":"string","description":"Permission group ID to assign to the user.","format":"uuid"}},"required":["groupId"]},"AdminServerResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the server.","example":"da1c4709-9723-4df5-9587-1cabb675611c"},"ownerId":{"type":"string","description":"The ID of the owner of the server.","example":"6fdbdb34-bd55-4d7b-8094-c72e9e0a4fa4"},"slug":{"type":"string","description":"The slug of the server.","example":"my-server"},"name":{"type":"string","description":"The name of the server.","example":"My Server"},"description":{"type":"string","description":"The description of the server.","example":"This is a description of my server."},"tags":{"description":"The tags of the server.","example":["Sandbox","Roleplay","PvP"],"type":"array","items":{"type":"string"}},"contentRating":{"type":"string","description":"The content rating of the server.","example":"Everyone"},"contentRatingStatus":{"type":"string","description":"The trust-and-safety review status of the content rating.","example":"pending_review"},"contentRatingDeclaredAt":{"type":"object","nullable":true},"contentRatingReviewedAt":{"type":"object","nullable":true},"gameMode":{"type":"string","description":"The game mode of the server.","example":"Sandbox"},"hostingType":{"type":"string","description":"The hosting type of the server.","example":"Dedicated"},"gameVersion":{"type":"string","description":"The game version of the server.","example":"1.0.0"},"worldId":{"type":"string","description":"The world ID of the server.","example":"e4412457-5bd4-44e2-a219-80fd3944d378"},"ipAddress":{"type":"string","description":"The IP address of the server.","example":"127.0.0.1"},"port":{"type":"number","description":"The port of the server.","example":7777},"currentPlayers":{"type":"number","description":"The current number of players on the server.","example":10},"maxPlayers":{"type":"number","description":"The maximum number of players on the server.","example":64},"playerIds":{"description":"The IDs of the players on the server.","example":["9669d149-349e-4bca-a58a-c8e1614bbc63","f3735be6-0ebc-4007-a9c7-1fe1ad0884b6","4b7bc58d-5906-404f-82a6-0c1f52d489d2"],"type":"array","items":{"type":"string"}},"status":{"type":"string","description":"The status of the server.","example":"Online"},"visits":{"type":"number","description":"The number of visits to the server.","example":12345},"currentRating":{"type":"number","description":"The current rating of the server.","example":4.5},"totalRatings":{"type":"number","description":"The total number of ratings for the server.","example":1337},"previews":{"description":"The previews of the package.","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"region":{"type":"string","description":"The server's region (2-letter ISO code).","example":"US","nullable":true},"heartbeatAddress":{"type":"object","description":"Heartbeat server address (provisioned servers only).","nullable":true},"nucleusIport":{"type":"object","description":"Nucleus internal port (provisioned servers only).","nullable":true},"workspaceId":{"type":"object","description":"Workspace ID (provisioned servers only).","nullable":true},"levelAsset":{"type":"object","description":"Level asset path (provisioned servers only).","nullable":true},"sideloadPaks":{"type":"object","description":"Comma-separated sideload pak files (provisioned servers only).","nullable":true},"systemDependencies":{"type":"object","description":"System dependencies (provisioned servers only).","nullable":true},"isPrivate":{"type":"boolean","description":"Whether the server is private.","example":false},"isFavorited":{"type":"boolean","description":"Whether the current authenticated user has favorited this server.","example":false},"whitelist":{"description":"Users whitelisted to access this private server.","type":"array","items":{"$ref":"#/components/schemas/UserResponseDto"}},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the server was published.","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"The date and time the server was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the server was updated."},"lastTimeOnline":{"format":"date-time","type":"string","description":"The date and time the server was last online (last heartbeat received).","nullable":true},"owner":{"description":"The owner of the server.","allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]},"world":{"description":"The world definition for the server.","allOf":[{"$ref":"#/components/schemas/ServerPackageWithDetailsResponseDto"}]},"isSuspended":{"type":"boolean","description":"Whether the server is currently suspended.","example":false},"moderationStatus":{"type":"string","description":"The moderation status of the server.","enum":["Active","Suspended","TakenDown"],"example":"Active"},"moderationReason":{"type":"object","description":"The reason recorded for the last moderation action.","nullable":true},"moderatedById":{"type":"object","description":"The ID of the admin who last moderated this server.","nullable":true},"moderatedAt":{"format":"date-time","type":"string","description":"When the server was last moderated.","nullable":true}},"required":["id","ownerId","slug","name","description","tags","contentRating","contentRatingStatus","gameMode","hostingType","gameVersion","worldId","ipAddress","port","currentPlayers","maxPlayers","playerIds","status","visits","currentRating","totalRatings","previews","region","isPrivate","whitelist","publishedAt","createdAt","updatedAt","lastTimeOnline","owner","world","isSuspended","moderationStatus"]},"ServerAuditLogResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The audit log entry ID."},"serverId":{"type":"object","description":"The server the action was taken against.","nullable":true},"adminId":{"type":"object","description":"The admin who performed the action.","nullable":true},"action":{"type":"string","description":"The action performed.","enum":["suspend","unsuspend","takedown","restore","force_offline","edit","delete","restart","update","wipe","transfer_ownership","override_rating","notify_owner"]},"reason":{"type":"object","description":"Reason recorded for the action.","nullable":true},"metadata":{"type":"object","description":"Structured metadata (e.g. before/after diff).","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"When the action was performed."}},"required":["id","serverId","adminId","action","reason","metadata","createdAt"]},"ConfirmServerMediaRequestDto":{"type":"object","properties":{"previewKeys":{"description":"Preview image keys that were uploaded and should be scanned.","example":["preview_1","preview_2"],"type":"array","items":{"type":"string"}},"thumbnailKeys":{"description":"Thumbnail image keys that were uploaded and should be scanned.","example":["thumb_1"],"type":"array","items":{"type":"string"}}}},"ModerateServerRequestDto":{"type":"object","properties":{"reason":{"type":"string","description":"Reason for the moderation action (recorded in the audit log).","example":"Repeated content-policy violations."}}},"NotifyOwnerRequestDto":{"type":"object","properties":{"title":{"type":"string","description":"Notification title.","example":"Action required on your server"},"message":{"type":"string","description":"Notification message body.","example":"Your server \"My World\" has been suspended pending review."}},"required":["title","message"]},"CreatePackageVersionPartialResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the package version.","example":"7a65e3e1-4369-4486-ba2b-ce0d84d24508"},"packageId":{"type":"string","description":"The ID of the package.","example":"123e4567-e89b-12d3-a456-426614174000"},"revision":{"type":"number","description":"The revision number for this package version.","example":1},"name":{"type":"string","description":"[DEPRECATED] The name of the package version. Always returns \"0.0.0\".","example":"0.0.0","deprecated":true},"config":{"type":"object","description":"The configuration of the package version.","example":{"fieldOne":"valueOne","fieldTwo":"valueTwo"}},"clientSize":{"type":"number","description":"The client size of the package version.","example":37434163},"serverSize":{"type":"number","description":"The server size of the package version.","example":37434163},"editorSize":{"type":"number","description":"The editor size of the package version.","example":37434163},"metadataSize":{"type":"number","description":"The metadata size of the package version.","example":1024},"releaseNotes":{"type":"object","description":"Release notes describing changes for this version.","example":"Fixed bugs and improved performance.","nullable":true},"engineVersion":{"type":"string","description":"The supported engine version for this package version. Package versions do not select a platform independently; the current HELIX Unreal runtime target is Win64 only.","example":"5.7"},"clientUrl":{"type":"string","description":"The URL of the client pak file for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/client"},"serverUrl":{"type":"string","description":"The URL of the server pak file for this packageversion.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/server"},"editorUrl":{"type":"string","description":"The URL of the editor for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/editor"},"metadataUrl":{"type":"string","description":"The URL of the metadata for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/metadata"},"files":{"description":"Flexible files payload including upload/download URL details.","type":"array","items":{"$ref":"#/components/schemas/PackageVersionFileResponseDto"}},"createdAt":{"format":"date-time","type":"string","description":"The date and time the package version was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the package version was updated."},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the package version was published.","nullable":true},"dependencyIds":{"description":"The immediate upstream dependency IDs for this package version.","example":["a00db5c3-73b8-4f92-b7cd-7ee843b16dc3","45148b3b-a28a-411f-bb37-f4575e32b509"],"type":"array","items":{"type":"string"}},"dependentIds":{"description":"The immediate downstream dependents for this package version.","example":["174427b0-f3e2-4975-8599-1e9c49e7db53","2e85e458-6192-421f-b84e-7481c2050c53"],"type":"array","items":{"type":"string"}},"clientUploadUrl":{"type":"string","description":"The upload URL of the package version's client pak/resource file (present only for non-multipart uploads).","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/client?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ccea4b41961a24576dbb314966338c9a%2F20250507%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20250507T111758Z&X-Amz-Expires=3600&X-Amz-Signature=dcf9b275e41eed6e768035eb341403593aea796dac60030ada895035a3f9c880&X-Amz-SignedHeaders=host&x-id=PutObject"},"serverUploadUrl":{"type":"string","description":"The upload URL of the package version's server pak/resource file (present only for non-multipart uploads).","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/server?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ccea4b41961a24576dbb314966338c9a%2F20250507%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20250507T111758Z&X-Amz-Expires=3600&X-Amz-Signature=b6f75cac4deab2e2dea367ef1342e321393bcf1119f2d2261a4ea658d9895a7a&X-Amz-SignedHeaders=host&x-id=PutObject"},"editorUploadUrl":{"type":"string","description":"The upload URL of the package version's editor pak/resource file (present only for non-multipart uploads).","example":"https://example.com/upload-url-for-editor?uploadId=abc123&signature=def456"},"metadataUploadUrl":{"type":"string","description":"The upload URL of the package version's metadata file (present only for non-multipart uploads).","example":"https://example.com/upload-url-for-metadata?uploadId=abc123&signature=def456"},"clientUploadMultipartUrls":{"description":"Multipart upload URLs for the client file when size exceeds the server multipart threshold.","example":[{"partNumber":1,"partUrl":"https://example.com/...&partNumber=1&uploadId=abcd"},{"partNumber":2,"partUrl":"https://example.com/...&partNumber=2&uploadId=abcd"}],"type":"array","items":{"$ref":"#/components/schemas/UploadMultipartPartDto"}},"serverUploadMultipartUrls":{"description":"Multipart upload URLs for the server file when size exceeds the server multipart threshold.","type":"array","items":{"$ref":"#/components/schemas/UploadMultipartPartDto"}},"editorUploadMultipartUrls":{"description":"Multipart upload URLs for the editor file when size exceeds the server multipart threshold.","type":"array","items":{"$ref":"#/components/schemas/UploadMultipartPartDto"}},"metadataUploadMultipartUrls":{"description":"Multipart upload URLs for the metadata file when size exceeds the server multipart threshold.","type":"array","items":{"$ref":"#/components/schemas/UploadMultipartPartDto"}}},"required":["id","packageId","revision","name","config","clientSize","serverSize","editorSize","metadataSize","releaseNotes","engineVersion","clientUrl","serverUrl","editorUrl","metadataUrl","createdAt","updatedAt","publishedAt","dependencyIds","dependentIds"]},"CreatePackageResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the package.","example":"123e4567-e89b-12d3-a456-426614174000"},"creatorId":{"type":"string","description":"The ID of the creator of the package.","example":"6fdbdb34-bd55-4d7b-8094-c72e9e0a4fa4"},"name":{"type":"string","description":"The name of the package.","example":"My Package"},"slug":{"type":"string","description":"The slug of the package.","example":"my-package"},"description":{"type":"string","description":"The description of the package.","example":"This is a description of my package."},"type":{"type":"string","description":"The type of the package.","example":"game"},"contentRating":{"type":"string","description":"The content rating of the package.","example":"Everyone"},"contentRatingStatus":{"type":"string","description":"The trust-and-safety review status of the content rating.","example":"pending_review"},"contentRatingDeclaredAt":{"type":"object","nullable":true},"contentRatingReviewedAt":{"type":"object","nullable":true},"previews":{"description":"The previews of the package.","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"tags":{"description":"The tags of the package.","example":["Sandbox","Roleplay","PvP"],"type":"array","items":{"type":"string"}},"downloads":{"type":"number","description":"The number of downloads of the package.","example":100},"currentRating":{"type":"number","description":"The current rating of the package.","example":4.5},"totalRatings":{"type":"number","description":"The total number of ratings of the package.","example":100},"isPrivate":{"type":"boolean","description":"Whether the package is private.","example":false},"engineVersion":{"type":"string","description":"The engine version supported by this package. All package versions inherit this value. The current HELIX Unreal runtime target is Win64 only.","example":"5.7"},"priceLix":{"type":"number","description":"The price in LIX for the package.","example":10.5},"thumbsUpPercentage":{"type":"string","example":"85%","description":"The thumbs up percentage for this package."},"totalReviews":{"type":"number","description":"The total number of reviews for this package.","example":42},"serverCreationPermission":{"type":"string","description":"Who may create a persistent server for the world backing this package. Null when no world mirrors this package — treat as \"not allowed\" rather than assuming a default.","enum":["creator","collaborators","anyone","nobody"],"nullable":true,"example":"anyone"},"createdAt":{"format":"date-time","type":"string","description":"The date and time the package was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the package was updated."},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the package was published.","nullable":true},"lastReleaseAt":{"format":"date-time","type":"string","description":"The date and time of the last release (latest version) of the package.","nullable":true},"creator":{"description":"The creator of the package.","allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]},"previewUploadUrls":{"description":"The upload URLs of the package previews.","example":["https://example.com/123e4567-e89b-12d3-a456-426614174000/previews/Preview_1","https://example.com/123e4567-e89b-12d3-a456-426614174000/previews/Preview_2"],"type":"array","items":{"type":"string"}},"latestVersion":{"description":"The latest version of the package.","allOf":[{"$ref":"#/components/schemas/CreatePackageVersionPartialResponseDto"}]}},"required":["id","creatorId","name","slug","description","type","contentRating","contentRatingStatus","previews","tags","downloads","currentRating","totalRatings","isPrivate","engineVersion","priceLix","thumbsUpPercentage","totalReviews","createdAt","updatedAt","publishedAt","lastReleaseAt","creator","previewUploadUrls","latestVersion"]},"PackageVersionFileRequestDto":{"type":"object","properties":{"key":{"type":"string","description":"File key used under a package version path (for example: client, server, editor, metadata, or any custom key). These keys are build roles, not platform selectors; HELIX currently consumes Unreal packages on Win64 only.","example":"client"},"size":{"type":"number","description":"File size in bytes.","example":1024,"minimum":0,"maximum":9007199254740991},"metadata":{"type":"object","description":"Arbitrary JSON metadata attached to this file entry. This is metadata about the file, not the legacy metadata asset itself.","default":{}}},"required":["key","size"]},"CreatePackageInitialVersionRequestDto":{"type":"object","properties":{"clientSize":{"type":"number","description":"Legacy client size in bytes (backward compatible). Prefer using files[] with key=\"client\".","example":37434163,"default":0},"serverSize":{"type":"number","description":"Legacy server size in bytes (backward compatible). Prefer using files[] with key=\"server\".","example":37434163,"default":0},"editorSize":{"type":"number","description":"Legacy editor size in bytes (backward compatible). Prefer using files[] with key=\"editor\".","example":37434163,"default":0},"metadataSize":{"type":"number","description":"Legacy metadata asset size in bytes (backward compatible). Prefer using files[] with key=\"metadata\".","example":1024,"default":0},"config":{"type":"object","description":"The configuration of the package version as a JSON object.","example":{"fieldOne":"valueOne","fieldTwo":"valueTwo"},"default":{}},"releaseNotes":{"type":"object","description":"Release notes describing changes for this version.","example":"Added new features and bug fixes.","nullable":true,"default":null},"engineVersion":{"type":"string","description":"[DEPRECATED] Engine version is controlled by the parent package. Any provided value is ignored.","example":"5.7","deprecated":true},"dependencyIds":{"description":"The dependency IDs of the package version.","example":["a00db5c3-73b8-4f92-b7cd-7ee843b16dc3","45148b3b-a28a-411f-bb37-f4575e32b509"],"default":[],"type":"array","items":{"type":"string"}},"files":{"description":"Preferred upload contract. Provide one object per file with key, size, and optional metadata. Supports legacy keys (client/server/editor/metadata) and custom keys.","example":[{"key":"client","size":37434163,"metadata":{}},{"key":"metadata","size":1024,"metadata":{"format":"json"}},{"key":"locales/en/client","size":2048,"metadata":{"locale":"en"}}],"type":"array","items":{"$ref":"#/components/schemas/PackageVersionFileRequestDto"}}}},"CreatePackageRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the package.","example":"My Package"},"slug":{"type":"string","description":"The slug of the package.","example":"my-package"},"description":{"type":"string","description":"The description of the package.","example":"This is a description of my package."},"type":{"type":"string","description":"The type of the package.","example":"Map","default":"Map"},"contentRating":{"type":"string","description":"The content rating of the package.","example":"Everyone","default":"Everyone"},"isPrivate":{"type":"boolean","description":"Whether the package is private.","example":false,"default":false},"isEncrypted":{"type":"boolean","description":"Whether this package is encrypted. All package versions inherit this value.","example":false,"default":false},"engineVersion":{"type":"string","description":"The engine version supported by this package. All package versions inherit this value. HELIX currently consumes packaged Unreal content on Win64 only; this field does not enable other platform targets.","example":"5.7","default":"5.7"},"previewKeys":{"description":"An array of keys of the package previews.","example":["Preview_1","Preview_2"],"default":[],"type":"array","items":{"type":"string"}},"tags":{"description":"The tags of the package.","example":["Sandbox","Roleplay","PvP"],"default":["Sandbox"],"type":"array","items":{"type":"string"}},"priceLix":{"type":"number","description":"The price in Lix currency for the package.","example":0,"default":0},"version":{"description":"Initial package version payload. Same contract as create package version, except packageId is omitted because it is inferred from the newly created package.","default":{"clientSize":0,"serverSize":0,"editorSize":0,"metadataSize":0,"config":{},"releaseNotes":null,"dependencyIds":[]},"example":{"files":[{"key":"client","size":37434163,"metadata":{}},{"key":"metadata","size":1024,"metadata":{"format":"json"}}],"releaseNotes":"Initial release","dependencyIds":[],"config":{}},"allOf":[{"$ref":"#/components/schemas/CreatePackageInitialVersionRequestDto"}]}},"required":["name","slug","description"]},"PackageCollectionWithUserScoreResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the package.","example":"123e4567-e89b-12d3-a456-426614174000"},"creatorId":{"type":"string","description":"The ID of the creator of the package.","example":"6fdbdb34-bd55-4d7b-8094-c72e9e0a4fa4"},"name":{"type":"string","description":"The name of the package.","example":"My Package"},"slug":{"type":"string","description":"The slug of the package.","example":"my-package"},"description":{"type":"string","description":"The description of the package.","example":"This is a description of my package."},"type":{"type":"string","description":"The type of the package.","example":"game"},"contentRating":{"type":"string","description":"The content rating of the package.","example":"Everyone"},"contentRatingStatus":{"type":"string","description":"The trust-and-safety review status of the content rating.","example":"pending_review"},"contentRatingDeclaredAt":{"type":"object","nullable":true},"contentRatingReviewedAt":{"type":"object","nullable":true},"previews":{"description":"The previews of the package.","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"tags":{"description":"The tags of the package.","example":["Sandbox","Roleplay","PvP"],"type":"array","items":{"type":"string"}},"downloads":{"type":"number","description":"The number of downloads of the package.","example":100},"currentRating":{"type":"number","description":"The current rating of the package.","example":4.5},"totalRatings":{"type":"number","description":"The total number of ratings of the package.","example":100},"isPrivate":{"type":"boolean","description":"Whether the package is private.","example":false},"engineVersion":{"type":"string","description":"The engine version supported by this package. All package versions inherit this value. The current HELIX Unreal runtime target is Win64 only.","example":"5.7"},"priceLix":{"type":"number","description":"The price in LIX for the package.","example":10.5},"thumbsUpPercentage":{"type":"string","example":"80%","description":"Percentage of thumbs up reviews."},"totalReviews":{"type":"number","description":"The total number of reviews for the package.","example":42},"serverCreationPermission":{"type":"string","description":"Who may create a persistent server for the world backing this package. Null when no world mirrors this package — treat as \"not allowed\" rather than assuming a default.","enum":["creator","collaborators","anyone","nobody"],"nullable":true,"example":"anyone"},"createdAt":{"format":"date-time","type":"string","description":"The date and time the package was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the package was updated."},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the package was published.","nullable":true},"lastReleaseAt":{"format":"date-time","type":"string","description":"The date and time of the last release (latest version) of the package.","nullable":true},"latestVersion":{"description":"The latest version of the package.","allOf":[{"$ref":"#/components/schemas/PackageVersionPartialResponseDto"}]},"creator":{"description":"The creator of the package.","allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]},"userScore":{"type":"number","description":"The score given by the current authenticated user for this package. 1 for thumbs up, -1 for thumbs down, null if the user has not rated this package.","example":1,"nullable":true,"enum":[1,-1]},"isFavorited":{"type":"boolean","description":"Whether the current authenticated user has favorited this package.","example":false}},"required":["id","creatorId","name","slug","description","type","contentRating","contentRatingStatus","previews","tags","downloads","currentRating","totalRatings","isPrivate","engineVersion","priceLix","thumbsUpPercentage","totalReviews","createdAt","updatedAt","publishedAt","lastReleaseAt","latestVersion","creator","userScore","isFavorited"]},"PackageWithUserScoreResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the package.","example":"123e4567-e89b-12d3-a456-426614174000"},"creatorId":{"type":"string","description":"The ID of the creator of the package.","example":"6fdbdb34-bd55-4d7b-8094-c72e9e0a4fa4"},"name":{"type":"string","description":"The name of the package.","example":"My Package"},"slug":{"type":"string","description":"The slug of the package.","example":"my-package"},"description":{"type":"string","description":"The description of the package.","example":"This is a description of my package."},"type":{"type":"string","description":"The type of the package.","example":"game"},"contentRating":{"type":"string","description":"The content rating of the package.","example":"Everyone"},"contentRatingStatus":{"type":"string","description":"The trust-and-safety review status of the content rating.","example":"pending_review"},"contentRatingDeclaredAt":{"type":"object","nullable":true},"contentRatingReviewedAt":{"type":"object","nullable":true},"previews":{"description":"The previews of the package.","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"tags":{"description":"The tags of the package.","example":["Sandbox","Roleplay","PvP"],"type":"array","items":{"type":"string"}},"downloads":{"type":"number","description":"The number of downloads of the package.","example":100},"currentRating":{"type":"number","description":"The current rating of the package.","example":4.5},"totalRatings":{"type":"number","description":"The total number of ratings of the package.","example":100},"isPrivate":{"type":"boolean","description":"Whether the package is private.","example":false},"engineVersion":{"type":"string","description":"The engine version supported by this package. All package versions inherit this value. The current HELIX Unreal runtime target is Win64 only.","example":"5.7"},"priceLix":{"type":"number","description":"The price in LIX for the package.","example":10.5},"thumbsUpPercentage":{"type":"string","example":"80%","description":"Percentage of thumbs up reviews."},"totalReviews":{"type":"number","description":"The total number of reviews for the package.","example":42},"serverCreationPermission":{"type":"string","description":"Who may create a persistent server for the world backing this package. Null when no world mirrors this package — treat as \"not allowed\" rather than assuming a default.","enum":["creator","collaborators","anyone","nobody"],"nullable":true,"example":"anyone"},"createdAt":{"format":"date-time","type":"string","description":"The date and time the package was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the package was updated."},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the package was published.","nullable":true},"lastReleaseAt":{"format":"date-time","type":"string","description":"The date and time of the last release (latest version) of the package.","nullable":true},"latestVersion":{"description":"The latest version of the package.","allOf":[{"$ref":"#/components/schemas/PackageVersionPartialResponseDto"}]},"versions":{"description":"The versions of the package.","type":"array","items":{"$ref":"#/components/schemas/PackageVersionPartialResponseDto"}},"creator":{"description":"The creator of the package.","allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]},"userScore":{"type":"number","description":"The score given by the current authenticated user for this package. 1 for thumbs up, -1 for thumbs down, null if the user has not rated this package.","example":1,"nullable":true,"enum":[1,-1]},"isFavorited":{"type":"boolean","description":"Whether the current authenticated user has favorited this package.","example":false}},"required":["id","creatorId","name","slug","description","type","contentRating","contentRatingStatus","previews","tags","downloads","currentRating","totalRatings","isPrivate","engineVersion","priceLix","thumbsUpPercentage","totalReviews","createdAt","updatedAt","publishedAt","lastReleaseAt","latestVersion","versions","creator","userScore","isFavorited"]},"PackageVersionHealthResponseDto":{"type":"object","properties":{"packageVersionId":{"type":"string","description":"The package version ID that was checked.","example":"7a65e3e1-4369-4486-ba2b-ce0d84d24508"},"isHealthy":{"type":"boolean","description":"True when all dependencies exist, no duplicate package dependencies exist, and every dependency is on its latest revision.","example":false},"dependencyIds":{"description":"Sanitized unique dependency package version IDs.","example":["a00db5c3-73b8-4f92-b7cd-7ee843b16dc3","45148b3b-a28a-411f-bb37-f4575e32b509"],"type":"array","items":{"type":"string"}},"unhealthyDependencyIds":{"description":"Sanitized unique dependency IDs that violate health rules for any reason.","example":["45148b3b-a28a-411f-bb37-f4575e32b509"],"type":"array","items":{"type":"string"}},"missingDependencyIds":{"description":"Dependency IDs that do not resolve to an existing package version.","example":[],"type":"array","items":{"type":"string"}},"outdatedDependencyIds":{"description":"Dependency IDs that are not on the latest revision for their package.","example":["45148b3b-a28a-411f-bb37-f4575e32b509"],"type":"array","items":{"type":"string"}},"duplicatePackageDependencyIds":{"description":"Dependency IDs that create duplicate package dependencies (multiple versions from the same package).","example":["a00db5c3-73b8-4f92-b7cd-7ee843b16dc3"],"type":"array","items":{"type":"string"}}},"required":["packageVersionId","isHealthy","dependencyIds","unhealthyDependencyIds","missingDependencyIds","outdatedDependencyIds","duplicatePackageDependencyIds"]},"UserReviewUserResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the user.","example":"123e4567-e89b-12d3-a456-426614174000"},"username":{"type":"string","description":"The username of the user.","example":"exampleuser1"},"displayName":{"type":"object","description":"The display name of the user.","example":"Conqr","nullable":true},"bio":{"type":"object","description":"User's custom bio.","example":"My name is Conqr and I like ducks.","nullable":true},"avatarUrl":{"type":"object","description":"The URL to the user's avatar.","example":"https://users.helix-cdn.com/123e4567-e89b-12d3-a456-426614174000/avatar","nullable":true},"bannerUrl":{"type":"object","description":"The URL to the user's banner.","example":"https://users.helix-cdn.com/123e4567-e89b-12d3-a456-426614174000/banner","nullable":true},"country":{"type":"object","description":"User's country (self selected).","example":"US","nullable":true}},"required":["id","username","displayName","bio","avatarUrl","bannerUrl","country"]},"UserReviewWithFullUserResponseDto":{"type":"object","properties":{"id":{"type":"string","example":"b1e2c3d4-5678-1234-9abc-1234567890ab"},"packageId":{"type":"string","example":"c1d2e3f4-5678-1234-9abc-1234567890ab"},"message":{"type":"string","example":"Great package!"},"score":{"type":"number","example":1},"createdAt":{"format":"date-time","type":"string","example":"2025-07-08T12:34:56.000Z"},"updatedAt":{"format":"date-time","type":"string","example":"2025-07-08T12:34:56.000Z"},"user":{"description":"Full user information of the reviewer","allOf":[{"$ref":"#/components/schemas/UserReviewUserResponseDto"}]}},"required":["id","packageId","score","createdAt","updatedAt","user"]},"UserReviewsWithThumbsResponseDto":{"type":"object","properties":{"items":{"description":"List of user reviews with full user information","example":[{"id":"b1e2c3d4-5678-1234-9abc-1234567890ab","packageId":"c1d2e3f4-5678-1234-9abc-1234567890ab","message":"Great package!","score":1,"createdAt":"2025-07-08T12:34:56.000Z","updatedAt":"2025-07-08T12:34:56.000Z","user":{"id":"a1b2c3d4-5678-1234-9abc-1234567890ab","username":"testuser","displayName":"Test User","bio":"This is a test user bio","avatarUrl":"https://users.helix-cdn.com/a1b2c3d4-5678-1234-9abc-1234567890ab/avatar","bannerUrl":"https://users.helix-cdn.com/a1b2c3d4-5678-1234-9abc-1234567890ab/banner","country":"US"}}],"type":"array","items":{"type":"object"}},"totalItems":{"type":"number","description":"The total number of items in the collection.","example":100},"pagination":{"description":"The pagination information.","allOf":[{"$ref":"#/components/schemas/PaginationResponseDto"}]},"pageInfo":{"description":"Keyset/cursor pagination info for infinite scroll.","allOf":[{"$ref":"#/components/schemas/PageInfoResponseDto"}]},"thumbsUpPercentage":{"type":"string","example":"80%","description":"Percentage of thumbs up reviews."},"thumbsUpCount":{"type":"number","example":42,"description":"Total number of upvotes (thumbs up) for this package."},"thumbsDownCount":{"type":"number","example":8,"description":"Total number of downvotes (thumbs down) for this package."},"userReview":{"example":{"id":"b1e2c3d4-5678-1234-9abc-1234567890ab","packageId":"c1d2e3f4-5678-1234-9abc-1234567890ab","message":"This is my review!","score":1,"createdAt":"2025-07-08T12:34:56.000Z","updatedAt":"2025-07-08T12:34:56.000Z","user":{"id":"a1b2c3d4-5678-1234-9abc-1234567890ab","username":"currentuser","displayName":"Current User","bio":"This is the current user bio","avatarUrl":"https://users.helix-cdn.com/a1b2c3d4-5678-1234-9abc-1234567890ab/avatar","bannerUrl":"https://users.helix-cdn.com/a1b2c3d4-5678-1234-9abc-1234567890ab/banner","country":"US"}},"description":"The requesting user's own review for this package (if it exists).","nullable":true,"allOf":[{"$ref":"#/components/schemas/UserReviewWithFullUserResponseDto"}]}},"required":["items","totalItems","pagination","thumbsUpPercentage","thumbsUpCount","thumbsDownCount"]},"UpdatePackageResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the package.","example":"123e4567-e89b-12d3-a456-426614174000"},"creatorId":{"type":"string","description":"The ID of the creator of the package.","example":"6fdbdb34-bd55-4d7b-8094-c72e9e0a4fa4"},"name":{"type":"string","description":"The name of the package.","example":"My Package"},"slug":{"type":"string","description":"The slug of the package.","example":"my-package"},"description":{"type":"string","description":"The description of the package.","example":"This is a description of my package."},"type":{"type":"string","description":"The type of the package.","example":"game"},"contentRating":{"type":"string","description":"The content rating of the package.","example":"Everyone"},"contentRatingStatus":{"type":"string","description":"The trust-and-safety review status of the content rating.","example":"pending_review"},"contentRatingDeclaredAt":{"type":"object","nullable":true},"contentRatingReviewedAt":{"type":"object","nullable":true},"previews":{"description":"The previews of the package.","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"tags":{"description":"The tags of the package.","example":["Sandbox","Roleplay","PvP"],"type":"array","items":{"type":"string"}},"downloads":{"type":"number","description":"The number of downloads of the package.","example":100},"currentRating":{"type":"number","description":"The current rating of the package.","example":4.5},"totalRatings":{"type":"number","description":"The total number of ratings of the package.","example":100},"isPrivate":{"type":"boolean","description":"Whether the package is private.","example":false},"engineVersion":{"type":"string","description":"The engine version supported by this package. All package versions inherit this value. The current HELIX Unreal runtime target is Win64 only.","example":"5.7"},"priceLix":{"type":"number","description":"The price in LIX for the package.","example":10.5},"thumbsUpPercentage":{"type":"string","example":"80%","description":"Percentage of thumbs up reviews."},"totalReviews":{"type":"number","description":"The total number of reviews for the package.","example":42},"serverCreationPermission":{"type":"string","description":"Who may create a persistent server for the world backing this package. Null when no world mirrors this package — treat as \"not allowed\" rather than assuming a default.","enum":["creator","collaborators","anyone","nobody"],"nullable":true,"example":"anyone"},"createdAt":{"format":"date-time","type":"string","description":"The date and time the package was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the package was updated."},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the package was published.","nullable":true},"lastReleaseAt":{"format":"date-time","type":"string","description":"The date and time of the last release (latest version) of the package.","nullable":true},"latestVersion":{"description":"The latest version of the package.","allOf":[{"$ref":"#/components/schemas/PackageVersionPartialResponseDto"}]},"versions":{"description":"The versions of the package.","type":"array","items":{"$ref":"#/components/schemas/PackageVersionPartialResponseDto"}},"creator":{"description":"The creator of the package.","allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]},"previewUploadUrls":{"description":"The upload URLs of the package previews.","example":["https://example.com/123e4567-e89b-12d3-a456-426614174000/previews/Preview_1","https://example.com/123e4567-e89b-12d3-a456-426614174000/previews/Preview_2"],"type":"array","items":{"type":"string"}}},"required":["id","creatorId","name","slug","description","type","contentRating","contentRatingStatus","previews","tags","downloads","currentRating","totalRatings","isPrivate","engineVersion","priceLix","thumbsUpPercentage","totalReviews","createdAt","updatedAt","publishedAt","lastReleaseAt","latestVersion","versions","creator","previewUploadUrls"]},"UpdatePackageRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the package.","example":"My Package"},"description":{"type":"string","description":"The description of the package.","example":"This is a description of my package."},"type":{"type":"string","description":"The type of the package.","example":"Map"},"contentRating":{"type":"string","description":"The content rating of the package.","example":"Everyone"},"previewKeys":{"description":"An array of keys of the package previews.","example":["Preview_1","Preview_2"],"type":"array","items":{"type":"string"}},"tags":{"description":"The tags of the package.","example":["Sandbox","Roleplay","PvP"],"type":"array","items":{"type":"string"}},"priceLix":{"type":"number","description":"The price in Lix currency for the package.","example":99.99},"isPrivate":{"type":"boolean","description":"Whether the package is private.","example":false},"engineVersion":{"type":"string","description":"The engine version supported by this package. All package versions inherit this value. HELIX currently consumes packaged Unreal content on Win64 only; this field does not enable other platform targets.","example":"5.7"}}},"PackagePartialResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the package."},"creatorId":{"type":"string","description":"The ID of the creator of the package."},"name":{"type":"string","description":"The name of the package."},"slug":{"type":"string","description":"The slug of the package."},"description":{"type":"string","description":"The description of the package."},"type":{"type":"string","description":"The type of the package."},"contentRating":{"type":"string","description":"The content rating of the package."},"contentRatingStatus":{"type":"string","description":"The trust-and-safety review status of the content rating."},"previews":{"description":"The previews of the package.","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"tags":{"description":"The tags of the package.","type":"array","items":{"type":"string"}},"downloads":{"type":"number","description":"The number of downloads of the package."},"currentRating":{"type":"number","description":"The current rating of the package."},"totalRatings":{"type":"number","description":"The total number of ratings of the package."},"isPrivate":{"type":"boolean","description":"Whether the package is private."},"isEncrypted":{"type":"boolean","description":"Whether the package is encrypted."},"engineVersion":{"type":"string","description":"The engine version supported by this package. All package versions inherit this value."},"thumbsUpPercentage":{"type":"string","example":"80%","description":"Percentage of thumbs up reviews."},"totalReviews":{"type":"number","description":"The total number of reviews for the package.","example":42},"createdAt":{"format":"date-time","type":"string","description":"The date and time the package was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the package was updated."},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the package was published.","nullable":true},"lastReleaseAt":{"format":"date-time","type":"string","description":"The date and time of the last release (latest version) of the package.","nullable":true},"creator":{"description":"The creator of the package.","allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]}},"required":["id","creatorId","name","slug","description","type","contentRating","contentRatingStatus","previews","tags","downloads","currentRating","totalRatings","isPrivate","isEncrypted","engineVersion","thumbsUpPercentage","totalReviews","createdAt","updatedAt","publishedAt","lastReleaseAt","creator"]},"UpdatePackageVersionResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the package version.","example":"7a65e3e1-4369-4486-ba2b-ce0d84d24508"},"packageId":{"type":"string","description":"The ID of the package.","example":"123e4567-e89b-12d3-a456-426614174000"},"revision":{"type":"number","description":"The revision number for this package version.","example":1},"name":{"type":"string","description":"[DEPRECATED] The name of the package version. Always returns \"0.0.0\".","example":"0.0.0","deprecated":true},"config":{"type":"object","description":"The configuration of the package version.","example":{"fieldOne":"valueOne","fieldTwo":"valueTwo"}},"clientSize":{"type":"number","description":"The client size of the package version.","example":37434163},"serverSize":{"type":"number","description":"The server size of the package version.","example":37434163},"editorSize":{"type":"number","description":"The editor size of the package version.","example":37434163},"metadataSize":{"type":"number","description":"The metadata size of the package version.","example":1024},"releaseNotes":{"type":"object","description":"Release notes describing changes for this version.","example":"Fixed bugs and improved performance.","nullable":true},"engineVersion":{"type":"string","description":"The supported engine version for this package version. Package versions do not select a platform independently; the current HELIX Unreal runtime target is Win64 only.","example":"5.7"},"clientUrl":{"type":"string","description":"The URL of the client pak file for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/client"},"serverUrl":{"type":"string","description":"The URL of the server pak file for this packageversion.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/server"},"editorUrl":{"type":"string","description":"The URL of the editor for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/editor"},"metadataUrl":{"type":"string","description":"The URL of the metadata for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/metadata"},"files":{"description":"Flexible files payload including upload/download URL details.","type":"array","items":{"$ref":"#/components/schemas/PackageVersionFileResponseDto"}},"createdAt":{"format":"date-time","type":"string","description":"The date and time the package version was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the package version was updated."},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the package version was published.","nullable":true},"package":{"description":"The package that this package version belongs to.","allOf":[{"$ref":"#/components/schemas/PackagePartialResponseDto"}]},"dependencyIds":{"description":"The immediate upstream dependency IDs for this package version.","example":["a00db5c3-73b8-4f92-b7cd-7ee843b16dc3","45148b3b-a28a-411f-bb37-f4575e32b509"],"type":"array","items":{"type":"string"}},"dependentIds":{"description":"The immediate downstream dependents for this package version.","example":["174427b0-f3e2-4975-8599-1e9c49e7db53","2e85e458-6192-421f-b84e-7481c2050c53"],"type":"array","items":{"type":"string"}},"clientUploadUrl":{"type":"string","description":"The upload URL of the package version's client pak/resource file (present only for non-multipart uploads).","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/client?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ccea4b41961a24576dbb314966338c9a%2F20250507%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20250507T111758Z&X-Amz-Expires=3600&X-Amz-Signature=dcf9b275e41eed6e768035eb341403593aea796dac60030ada895035a3f9c880&X-Amz-SignedHeaders=host&x-id=PutObject"},"serverUploadUrl":{"type":"string","description":"The upload URL of the package version's server pak/resource file (present only for non-multipart uploads).","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/server?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ccea4b41961a24576dbb314966338c9a%2F20250507%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20250507T111758Z&X-Amz-Expires=3600&X-Amz-Signature=b6f75cac4deab2e2dea367ef1342e321393bcf1119f2d2261a4ea658d9895a7a&X-Amz-SignedHeaders=host&x-id=PutObject"},"editorUploadUrl":{"type":"string","description":"The upload URL of the package version's editor pak/resource file (present only for non-multipart uploads).","example":"https://example.com/upload-url-for-editor?uploadId=abc123&signature=def456"},"metadataUploadUrl":{"type":"string","description":"The upload URL of the package version's metadata file (present only for non-multipart uploads).","example":"https://example.com/upload-url-for-metadata?uploadId=abc123&signature=def456"},"clientUploadMultipartUrls":{"description":"Multipart upload URLs for the client file when size exceeds the server multipart threshold.","type":"array","items":{"$ref":"#/components/schemas/UploadMultipartPartDto"}},"serverUploadMultipartUrls":{"description":"Multipart upload URLs for the server file when size exceeds the server multipart threshold.","type":"array","items":{"$ref":"#/components/schemas/UploadMultipartPartDto"}},"editorUploadMultipartUrls":{"description":"Multipart upload URLs for the editor file when size exceeds the server multipart threshold.","type":"array","items":{"$ref":"#/components/schemas/UploadMultipartPartDto"}},"metadataUploadMultipartUrls":{"description":"Multipart upload URLs for the metadata file when size exceeds the server multipart threshold.","type":"array","items":{"$ref":"#/components/schemas/UploadMultipartPartDto"}}},"required":["id","packageId","revision","name","config","clientSize","serverSize","editorSize","metadataSize","releaseNotes","engineVersion","clientUrl","serverUrl","editorUrl","metadataUrl","createdAt","updatedAt","publishedAt","package","dependencyIds","dependentIds"]},"UpdatePackageVersionRequestDto":{"type":"object","properties":{"clientSize":{"type":"number","description":"Legacy client size patch in bytes (backward compatible). Prefer using files[] with key=\"client\".","example":37434163},"serverSize":{"type":"number","description":"Legacy server size patch in bytes (backward compatible). Prefer using files[] with key=\"server\".","example":37434163},"editorSize":{"type":"number","description":"Legacy editor size patch in bytes (backward compatible). Prefer using files[] with key=\"editor\".","example":37434163},"metadataSize":{"type":"number","description":"Legacy metadata asset size patch in bytes (backward compatible). Prefer using files[] with key=\"metadata\".","example":1024},"releaseNotes":{"type":"object","description":"Release notes describing changes for this version.","example":"Patched critical bug in AI logic.","nullable":true},"engineVersion":{"type":"string","description":"[DEPRECATED] Engine version is controlled by the parent package. Any provided value is ignored.","example":"5.7","deprecated":true},"config":{"type":"object","description":"The configuration of the package version as a JSON object.","example":{"fieldOne":"valueOne","fieldTwo":"valueTwo"}},"dependencyIds":{"description":"The dependency IDs of the package version.","example":["a00db5c3-73b8-4f92-b7cd-7ee843b16dc3","45148b3b-a28a-411f-bb37-f4575e32b509"],"type":"array","items":{"type":"string"}},"files":{"description":"Preferred patch contract. Replaces the entire files set using the provided order. Omitted keys are removed. Supports legacy keys (client/server/editor/metadata) and custom keys.","example":[{"key":"metadata","size":2048,"metadata":{"format":"json","source":"ci"}},{"key":"locales/fr/client","size":4096,"metadata":{"locale":"fr"}}],"type":"array","items":{"$ref":"#/components/schemas/PackageVersionFileRequestDto"}}}},"TransferOwnershipRequestDto":{"type":"object","properties":{"packageIds":{"description":"Array of package IDs to transfer","type":"array","items":{"type":"string"}},"userId":{"type":"string","description":"The target user ID who will become the new owner"}},"required":["packageIds","userId"]},"CreatePackageVersionResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the package version.","example":"7a65e3e1-4369-4486-ba2b-ce0d84d24508"},"packageId":{"type":"string","description":"The ID of the package.","example":"123e4567-e89b-12d3-a456-426614174000"},"revision":{"type":"number","description":"The revision number for this package version.","example":1},"name":{"type":"string","description":"[DEPRECATED] The name of the package version. Always returns \"0.0.0\".","example":"0.0.0","deprecated":true},"config":{"type":"object","description":"The configuration of the package version.","example":{"fieldOne":"valueOne","fieldTwo":"valueTwo"}},"clientSize":{"type":"number","description":"The client size of the package version.","example":37434163},"serverSize":{"type":"number","description":"The server size of the package version.","example":37434163},"editorSize":{"type":"number","description":"The editor size of the package version.","example":37434163},"metadataSize":{"type":"number","description":"The metadata size of the package version.","example":1024},"releaseNotes":{"type":"object","description":"Release notes describing changes for this version.","example":"Fixed bugs and improved performance.","nullable":true},"engineVersion":{"type":"string","description":"The supported engine version for this package version. Package versions do not select a platform independently; the current HELIX Unreal runtime target is Win64 only.","example":"5.7"},"clientUrl":{"type":"string","description":"The URL of the client pak file for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/client"},"serverUrl":{"type":"string","description":"The URL of the server pak file for this packageversion.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/server"},"editorUrl":{"type":"string","description":"The URL of the editor for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/editor"},"metadataUrl":{"type":"string","description":"The URL of the metadata for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/metadata"},"files":{"description":"Flexible files payload including upload/download URL details.","type":"array","items":{"$ref":"#/components/schemas/PackageVersionFileResponseDto"}},"createdAt":{"format":"date-time","type":"string","description":"The date and time the package version was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the package version was updated."},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the package version was published.","nullable":true},"package":{"description":"The package that this package version belongs to.","allOf":[{"$ref":"#/components/schemas/PackagePartialResponseDto"}]},"dependencyIds":{"description":"The immediate upstream dependency IDs for this package version.","example":["a00db5c3-73b8-4f92-b7cd-7ee843b16dc3","45148b3b-a28a-411f-bb37-f4575e32b509"],"type":"array","items":{"type":"string"}},"dependentIds":{"description":"The immediate downstream dependents for this package version.","example":["174427b0-f3e2-4975-8599-1e9c49e7db53","2e85e458-6192-421f-b84e-7481c2050c53"],"type":"array","items":{"type":"string"}},"clientUploadUrl":{"type":"string","description":"The upload URL of the package version's client pak/resource file (present only for non-multipart uploads).","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/client?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ccea4b41961a24576dbb314966338c9a%2F20250507%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20250507T111758Z&X-Amz-Expires=3600&X-Amz-Signature=dcf9b275e41eed6e768035eb341403593aea796dac60030ada895035a3f9c880&X-Amz-SignedHeaders=host&x-id=PutObject"},"serverUploadUrl":{"type":"string","description":"The upload URL of the package version's server pak/resource file (present only for non-multipart uploads).","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/server?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ccea4b41961a24576dbb314966338c9a%2F20250507%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20250507T111758Z&X-Amz-Expires=3600&X-Amz-Signature=b6f75cac4deab2e2dea367ef1342e321393bcf1119f2d2261a4ea658d9895a7a&X-Amz-SignedHeaders=host&x-id=PutObject"},"editorUploadUrl":{"type":"string","description":"The upload URL of the package version's editor pak/resource file (present only for non-multipart uploads).","example":"https://example.com/upload-url-for-editor?uploadId=abc123&signature=def456"},"metadataUploadUrl":{"type":"string","description":"The upload URL of the package version's metadata file (present only for non-multipart uploads).","example":"https://example.com/upload-url-for-metadata?uploadId=abc123&signature=def456"},"clientUploadMultipartUrls":{"description":"Multipart upload URLs for the client file when size exceeds the server multipart threshold.","example":[{"partNumber":1,"partUrl":"https://example.com/...&partNumber=1&uploadId=abcd"},{"partNumber":2,"partUrl":"https://example.com/...&partNumber=2&uploadId=abcd"}],"type":"array","items":{"$ref":"#/components/schemas/UploadMultipartPartDto"}},"serverUploadMultipartUrls":{"description":"Multipart upload URLs for the server file when size exceeds the server multipart threshold.","type":"array","items":{"$ref":"#/components/schemas/UploadMultipartPartDto"}},"editorUploadMultipartUrls":{"description":"Multipart upload URLs for the editor file when size exceeds the server multipart threshold.","type":"array","items":{"$ref":"#/components/schemas/UploadMultipartPartDto"}},"metadataUploadMultipartUrls":{"description":"Multipart upload URLs for the metadata file when size exceeds the server multipart threshold.","type":"array","items":{"$ref":"#/components/schemas/UploadMultipartPartDto"}}},"required":["id","packageId","revision","name","config","clientSize","serverSize","editorSize","metadataSize","releaseNotes","engineVersion","clientUrl","serverUrl","editorUrl","metadataUrl","createdAt","updatedAt","publishedAt","package","dependencyIds","dependentIds"]},"CreatePackageVersionRequestDto":{"type":"object","properties":{"packageId":{"type":"string","description":"The package ID of the package version.","example":"a00db5c3-73b8-4f92-b7cd-7ee843b16dc3"},"clientSize":{"type":"number","description":"Legacy client size in bytes (backward compatible). Prefer using files[] with key=\"client\".","example":37434163,"default":0},"serverSize":{"type":"number","description":"Legacy server size in bytes (backward compatible). Prefer using files[] with key=\"server\".","example":37434163,"default":0},"editorSize":{"type":"number","description":"Legacy editor size in bytes (backward compatible). Prefer using files[] with key=\"editor\".","example":37434163,"default":0},"metadataSize":{"type":"number","description":"Legacy metadata asset size in bytes (backward compatible). Prefer using files[] with key=\"metadata\".","example":1024,"default":0},"config":{"type":"object","description":"The configuration of the package version as a JSON object.","example":{"fieldOne":"valueOne","fieldTwo":"valueTwo"},"default":{}},"releaseNotes":{"type":"object","description":"Release notes describing changes for this version.","example":"Added new features and bug fixes.","nullable":true,"default":null},"engineVersion":{"type":"string","description":"[DEPRECATED] Engine version is controlled by the parent package. Any provided value is ignored.","example":"5.7","deprecated":true},"dependencyIds":{"description":"The dependency IDs of the package version.","example":["a00db5c3-73b8-4f92-b7cd-7ee843b16dc3","45148b3b-a28a-411f-bb37-f4575e32b509"],"default":[],"type":"array","items":{"type":"string"}},"files":{"description":"Preferred upload contract. Provide one object per file with key, size, and optional metadata. Supports legacy keys (client/server/editor/metadata) and custom keys.","example":[{"key":"client","size":37434163,"metadata":{}},{"key":"metadata","size":1024,"metadata":{"format":"json"}},{"key":"locales/en/client","size":2048,"metadata":{"locale":"en"}}],"type":"array","items":{"$ref":"#/components/schemas/PackageVersionFileRequestDto"}}},"required":["packageId"]},"CompleteMultipartUploadPartDto":{"type":"object","properties":{"partNumber":{"type":"number","description":"Part sequence number starting at 1.","example":1,"minimum":1},"eTag":{"type":"string","description":"ETag returned from the UploadPart response for this part. With or without surrounding quotes.","example":"\"f1c9645dbc14efddc7d8a322685f26eb\""}},"required":["partNumber","eTag"]},"CompleteMultipartUploadRequestDto":{"type":"object","properties":{"asset":{"type":"string","description":"Which legacy asset the multipart upload targets. Use key for flexible file payloads.","enum":["client","server","editor","metadata"]},"key":{"type":"string","description":"Flexible file key to complete multipart upload for package version files array.","example":"locales/en/client"},"uploadId":{"type":"string","description":"Upload ID returned when initiating the multipart upload.","example":"AAHLzkQlPdiElELRMIM6TnEMC..."},"parts":{"description":"All uploaded parts with their ETags.","type":"array","items":{"$ref":"#/components/schemas/CompleteMultipartUploadPartDto"}}},"required":["uploadId","parts"]},"CompleteMultipartUploadResponseDto":{"type":"object","properties":{"asset":{"type":"string","description":"Asset that was assembled.","example":"client"},"status":{"type":"string","description":"Completion status.","example":"Completed"},"location":{"type":"string","description":"Final object location URL."},"etag":{"type":"string","description":"Final object ETag (if provided by R2)."}},"required":["asset","status","location"]},"CompleteSingleUploadRequestDto":{"type":"object","properties":{"asset":{"type":"string","description":"Which legacy asset the single-PUT upload targets. Use key for flexible file payloads.","enum":["client","server","editor","metadata"]},"key":{"type":"string","description":"Flexible file key to confirm the single-PUT upload for a package version files array.","example":"locales/en/client"}}},"CompleteSingleUploadResponseDto":{"type":"object","properties":{"asset":{"type":"string","description":"Asset that was confirmed.","example":"client"},"status":{"type":"string","description":"Completion status.","example":"Completed"},"location":{"type":"string","description":"Final object location URL."},"etag":{"type":"string","description":"Final object ETag (from R2 HeadObject)."}},"required":["asset","status","location"]},"PackageVersionResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the package version.","example":"7a65e3e1-4369-4486-ba2b-ce0d84d24508"},"packageId":{"type":"string","description":"The ID of the package.","example":"123e4567-e89b-12d3-a456-426614174000"},"revision":{"type":"number","description":"The revision number for this package version.","example":1},"name":{"type":"string","description":"[DEPRECATED] The name of the package version. Always returns \"0.0.0\".","example":"0.0.0","deprecated":true},"config":{"type":"object","description":"The configuration of the package version.","example":{"fieldOne":"valueOne","fieldTwo":"valueTwo"}},"clientSize":{"type":"number","description":"The client size of the package version.","example":37434163},"serverSize":{"type":"number","description":"The server size of the package version.","example":37434163},"editorSize":{"type":"number","description":"The editor size of the package version.","example":37434163},"metadataSize":{"type":"number","description":"The metadata size of the package version.","example":1024},"releaseNotes":{"type":"object","description":"Release notes describing changes for this version.","example":"Fixed bugs and improved performance.","nullable":true},"engineVersion":{"type":"string","description":"The supported engine version for this package version. Package versions do not select a platform independently; the current HELIX Unreal runtime target is Win64 only.","example":"5.7"},"clientUrl":{"type":"string","description":"The URL of the client pak file for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/client"},"serverUrl":{"type":"string","description":"The URL of the server pak file for this packageversion.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/server"},"editorUrl":{"type":"string","description":"The URL of the editor for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/editor"},"metadataUrl":{"type":"string","description":"The URL of the metadata for this package version.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/metadata"},"files":{"description":"Flexible package version files payload.","type":"array","items":{"$ref":"#/components/schemas/PackageVersionFileResponseDto"}},"createdAt":{"format":"date-time","type":"string","description":"The date and time the package version was created."},"updatedAt":{"format":"date-time","type":"string","description":"The date and time the package version was updated."},"publishedAt":{"format":"date-time","type":"string","description":"The date and time the package version was published.","nullable":true},"package":{"description":"The package that this package version belongs to.","allOf":[{"$ref":"#/components/schemas/PackagePartialResponseDto"}]},"dependencyIds":{"description":"The immediate upstream dependency IDs for this package version.","example":["a00db5c3-73b8-4f92-b7cd-7ee843b16dc3","45148b3b-a28a-411f-bb37-f4575e32b509"],"type":"array","items":{"type":"string"}},"dependentIds":{"description":"The immediate downstream dependents for this package version.","example":["174427b0-f3e2-4975-8599-1e9c49e7db53","2e85e458-6192-421f-b84e-7481c2050c53"],"type":"array","items":{"type":"string"}}},"required":["id","packageId","revision","name","config","clientSize","serverSize","editorSize","metadataSize","releaseNotes","engineVersion","clientUrl","serverUrl","editorUrl","metadataUrl","createdAt","updatedAt","publishedAt","package","dependencyIds","dependentIds"]},"PackageVersionKeysResponseDto":{"type":"object","properties":{"serverKey":{"type":"object","description":"Unwrapped server CEK, base64-encoded. Null if this version has no server-category protected files.","nullable":true},"clientKey":{"type":"object","description":"Unwrapped client CEK, base64-encoded. Null if this version has no client/shared-category protected files.","nullable":true}},"required":["serverKey","clientKey"]},"CreatePackageVersionAssetResponseDto":{"type":"object","properties":{"key":{"type":"string","description":"The key of the asset.","example":"thumbnail"},"type":{"type":"string","description":"The type of the asset.","example":"StaticMesh"},"url":{"type":"string","description":"The URL of the asset.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/thumbnail"},"uploadUrl":{"type":"string","description":"The upload URL of the asset.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/thumbnail?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ccea4b41961a24576dbb314966338c9a%2F20250507%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20250507T111758Z&X-Amz-Expires=3600&X-Amz-Signature=dcf9b275e41eed6e768035eb341403593aea796dac60030ada895035a3f9c880&X-Amz-SignedHeaders=host&x-id=PutObject"}},"required":["key","type","url","uploadUrl"]},"UpdatePackageVersionAssetResponseDto":{"type":"object","properties":{"key":{"type":"string","description":"The key of the asset.","example":"thumbnail"},"type":{"type":"string","description":"The type of the asset.","example":"StaticMesh"},"url":{"type":"string","description":"The URL of the asset.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/thumbnail"},"uploadUrl":{"type":"string","description":"The upload URL of the asset.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/thumbnail?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ccea4b41961a24576dbb314966338c9a%2F20250507%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20250507T111758Z&X-Amz-Expires=3600&X-Amz-Signature=dcf9b275e41eed6e768035eb341403593aea796dac60030ada895035a3f9c880&X-Amz-SignedHeaders=host&x-id=PutObject"}},"required":["key","type","url","uploadUrl"]},"PackageVersionAssetResponseDto":{"type":"object","properties":{"key":{"type":"string","description":"The key of the asset.","example":"thumbnail"},"type":{"type":"string","description":"The type of the asset.","example":"StaticMesh"},"url":{"type":"string","description":"The URL of the asset.","example":"https://example.com/123e4567-e89b-12d3-a456-426614174000/7a65e3e1-4369-4486-ba2b-ce0d84d24508/thumbnail"}},"required":["key","type","url"]},"PackageAccessResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Grant ID."},"packageId":{"type":"string","description":"Package ID."},"userId":{"type":"string","description":"User ID."},"role":{"type":"string","enum":["subscribed","purchased","granted"],"description":"Role type."},"startsAt":{"type":"object","description":"Start time of access.","nullable":true},"expiresAt":{"type":"object","description":"Expiry time of access.","nullable":true},"isActive":{"type":"boolean","description":"Whether the access is currently active."},"grantedById":{"type":"object","description":"User ID of the granter (if applicable).","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Created at timestamp."},"updatedAt":{"format":"date-time","type":"string","description":"Updated at timestamp."},"user":{"description":"User details for convenience.","allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]}},"required":["id","packageId","userId","role","startsAt","expiresAt","isActive","grantedById","createdAt","updatedAt","user"]},"BatchGrantResult":{"type":"object","properties":{"userId":{"type":"string","description":"User ID that was processed"},"success":{"type":"boolean","description":"Whether the grant was successful"},"error":{"type":"string","description":"Error message if the grant failed","nullable":true},"packageAccess":{"description":"Package access details if successful","nullable":true,"allOf":[{"$ref":"#/components/schemas/PackageAccessResponseDto"}]}},"required":["userId","success","error","packageAccess"]},"BatchGrantPackageAccessResponseDto":{"type":"object","properties":{"results":{"description":"Array of grant results for each user","type":"array","items":{"$ref":"#/components/schemas/BatchGrantResult"}},"totalProcessed":{"type":"number","description":"Total number of users processed"},"successCount":{"type":"number","description":"Number of successful grants"},"errorCount":{"type":"number","description":"Number of failed grants"}},"required":["results","totalProcessed","successCount","errorCount"]},"BatchGrantPackageAccessRequestDto":{"type":"object","properties":{"userIds":{"description":"Array of user IDs to grant access to (alternative to usernames)","example":["123e4567-e89b-12d3-a456-426614174000","123e4567-e89b-12d3-a456-426614174001"],"minItems":1,"maxItems":100,"type":"array","items":{"type":"string"}},"usernames":{"description":"Array of usernames to grant access to (alternative to userIds)","example":["user1","user2","user3"],"minItems":1,"maxItems":100,"type":"array","items":{"type":"string"}},"durationSeconds":{"description":"Duration in seconds or the string \"unlimited\". When set to \"unlimited\", the grant never expires (expiresAt = null).","oneOf":[{"type":"integer","minimum":1},{"type":"string","enum":["unlimited"]}],"examples":[2592000,"unlimited"]}},"required":["durationSeconds"]},"GrantPackageAccessRequestDto":{"type":"object","properties":{"durationSeconds":{"description":"Duration in seconds or the string \"unlimited\". When set to \"unlimited\", the grant never expires (expiresAt = null).","oneOf":[{"type":"integer","minimum":1},{"type":"string","enum":["unlimited"]}],"examples":[2592000,"unlimited"]}},"required":["durationSeconds"]},"UpdatePackageAccessRequestDto":{"type":"object","properties":{"durationSeconds":{"description":"New duration in seconds or the string \"unlimited\". When set to \"unlimited\", the grant never expires (expiresAt = null).","oneOf":[{"type":"integer","minimum":1},{"type":"string","enum":["unlimited"]}],"examples":[5184000,"unlimited"]}},"required":["durationSeconds"]},"PackageAccessRolesResponseDto":{"type":"object","properties":{"packageId":{"type":"string","description":"Package ID."},"userId":{"type":"string","description":"User ID."},"roles":{"description":"All access roles for this user on the package.","type":"array","items":{"$ref":"#/components/schemas/PackageAccessResponseDto"}}},"required":["packageId","userId","roles"]},"Domain":{"type":"object","properties":{}},"RegisterSubdomainRequestDto":{"type":"object","properties":{"subdomain":{"type":"string","description":"Subdomain label (without root domain).","example":"alpha","minLength":1,"maxLength":63}},"required":["subdomain"]},"DomainSubdomain":{"type":"object","properties":{}},"CreateWorldItemOrderDto":{"type":"object","properties":{"serverId":{"type":"string","description":"The UUID of the server creating the order","example":"123e4567-e89b-12d3-a456-426614174000"},"userId":{"type":"string","description":"The UUID of the user for whom the order is being created","example":"987fcdeb-51a2-43d7-8f9e-123456789abc"},"worldItemId":{"type":"string","description":"The UUID of the world item to order. If both worldItemId and worldItemSlug are provided, worldItemId takes precedence.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"worldItemSlug":{"type":"string","description":"The slug of the world item to order. If both worldItemId and worldItemSlug are provided, worldItemId takes precedence.","example":"legendary-sword"}},"required":["serverId","userId"]},"CreateServerPlanOrderDto":{"type":"object","properties":{"serverPlanId":{"type":"string","description":"The UUID of the server plan to order","example":"123e4567-e89b-12d3-a456-426614174000"},"billingPeriod":{"type":"string","description":"The billing period for the server plan subscription","enum":["Monthly"],"example":"Monthly"},"regionId":{"type":"string","description":"The Vultr region ID where the server will be provisioned","example":"ams"}},"required":["serverPlanId","billingPeriod","regionId"]},"WorldItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"ID of the world item"},"slug":{"type":"string","description":"Slug of the world item"},"name":{"type":"string","description":"Name of the world item"},"description":{"type":"string","description":"Description of the world item"},"thumbnail":{"type":"string","description":"Thumbnail URL"},"thumbnailUploadUrl":{"type":"string","description":"Presigned URL for uploading the thumbnail"},"priceLix":{"type":"number","description":"Price in Lix","example":99.99},"available":{"type":"boolean","description":"Whether the item is available"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Update timestamp"}},"required":["id","slug","name","description","thumbnail","thumbnailUploadUrl","priceLix","available","createdAt","updatedAt"]},"ServerPlanResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the server plan","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Name of the server plan","example":"Basic Plan"},"description":{"type":"object","description":"A short description of the plan","example":"Great for small communities and testing","nullable":true},"slug":{"type":"string","description":"URL-friendly unique identifier for the plan","example":"basic-plan"},"lixPrice":{"type":"number","description":"Price in LIX for this plan","example":100},"cpuCores":{"type":"number","description":"Number of CPU cores allocated","example":2},"ramMb":{"type":"number","description":"RAM in MB","example":4096},"storageMb":{"type":"number","description":"Storage in MB","example":51200},"trafficLimitMb":{"type":"object","description":"Traffic limit in MB per billing period. null = unlimited traffic","example":102400,"nullable":true},"billingPeriod":{"type":"string","description":"Billing period for this plan","enum":["Monthly"],"example":"Monthly"},"monthlyAvailable":{"type":"boolean","description":"Whether monthly billing is available for this plan","example":true},"availableRegions":{"description":"Available regions for this plan","example":["us-east","eu-west","asia-pacific"],"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean","description":"Whether this plan is active and available for purchase","example":true},"vultrPlanId":{"type":"object","description":"Vultr plan ID that corresponds to this server plan","example":"vhp-4c-8gb-amd","nullable":true},"ovhPlanId":{"type":"object","description":"OVH plan ID that corresponds to this server plan","example":"d2-4","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"Plan creation timestamp","example":"2024-01-15T10:30:00Z"},"updatedAt":{"format":"date-time","type":"string","description":"Plan last update timestamp","example":"2024-01-15T15:45:00Z"}},"required":["id","name","description","slug","lixPrice","cpuCores","ramMb","storageMb","trafficLimitMb","billingPeriod","monthlyAvailable","availableRegions","isActive","vultrPlanId","ovhPlanId","createdAt","updatedAt"]},"OrderResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Order ID"},"userId":{"type":"string","description":"User ID who placed the order"},"subtotalAmount":{"type":"number","description":"Subtotal amount in Lix","example":99.99},"taxAmount":{"type":"number","description":"Tax amount in Lix","example":0},"discountAmount":{"type":"number","description":"Discount amount in Lix","example":0},"totalAmount":{"type":"number","description":"Total amount in Lix","example":99.99},"status":{"type":"string","enum":["Pending","Escrowed","Paid","Failed","Canceled","Refunded"]},"itemType":{"type":"string","enum":["WorldItem","Collectible","Package","PackageSubscription","ServerPlan","KvStorage"]},"worldItem":{"$ref":"#/components/schemas/WorldItemResponseDto"},"itemThumbnail":{"type":"object","description":"Primary thumbnail URL for the ordered item when available","nullable":true},"itemImage":{"type":"object","description":"Primary image URL for the ordered item when available (3D image for collectibles)","nullable":true},"transactionId":{"type":"string","description":"Transaction ID linked to this order"},"paymentIntentId":{"type":"object","description":"Payment intent ID if applicable"},"checkoutSessionId":{"type":"object","description":"Checkout session ID if applicable"},"serverPlan":{"description":"Creation timestamp","nullable":true,"allOf":[{"$ref":"#/components/schemas/ServerPlanResponseDto"}]},"subscriptionPeriod":{"type":"object","description":"The subscription's billing period, e.g. 'Monthly'.","nullable":true},"subscriptionDuration":{"type":"object","description":"How many billing periods this order covers.","nullable":true},"updatedAt":{"format":"date-time","type":"string","description":"Update timestamp"}},"required":["id","userId","subtotalAmount","taxAmount","discountAmount","totalAmount","status","itemType","transactionId","updatedAt"]},"OrderWithWalletResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Order ID"},"userId":{"type":"string","description":"User ID who placed the order"},"subtotalAmount":{"type":"number","description":"Subtotal amount in Lix","example":99.99},"taxAmount":{"type":"number","description":"Tax amount in Lix","example":0},"discountAmount":{"type":"number","description":"Discount amount in Lix","example":0},"totalAmount":{"type":"number","description":"Total amount in Lix","example":99.99},"status":{"type":"string","enum":["Pending","Escrowed","Paid","Failed","Canceled","Refunded"]},"itemType":{"type":"string","enum":["WorldItem","Collectible","Package","PackageSubscription","ServerPlan","KvStorage"]},"worldItem":{"$ref":"#/components/schemas/WorldItemResponseDto"},"itemThumbnail":{"type":"object","description":"Primary thumbnail URL for the ordered item when available","nullable":true},"itemImage":{"type":"object","description":"Primary image URL for the ordered item when available (3D image for collectibles)","nullable":true},"transactionId":{"type":"string","description":"Transaction ID linked to this order"},"paymentIntentId":{"type":"object","description":"Payment intent ID if applicable"},"checkoutSessionId":{"type":"object","description":"Checkout session ID if applicable"},"serverPlan":{"description":"Creation timestamp","nullable":true,"allOf":[{"$ref":"#/components/schemas/ServerPlanResponseDto"}]},"subscriptionPeriod":{"type":"object","description":"The subscription's billing period, e.g. 'Monthly'.","nullable":true},"subscriptionDuration":{"type":"object","description":"How many billing periods this order covers.","nullable":true},"updatedAt":{"format":"date-time","type":"string","description":"Update timestamp"},"userWallet":{"description":"User wallet information","allOf":[{"$ref":"#/components/schemas/WalletResponseDto"}]}},"required":["id","userId","subtotalAmount","taxAmount","discountAmount","totalAmount","status","itemType","transactionId","updatedAt","userWallet"]},"RegionInfoDto":{"type":"object","properties":{"code":{"type":"string","example":"DE1"},"name":{"type":"string","example":"Germany"}},"required":["code","name"]},"PlanCodesDto":{"type":"object","properties":{"monthly":{"type":"string","example":"d2-2.monthly.postpaid"},"hourly":{"type":"string","example":"d2-2.consumption"},"license":{"type":"object","example":null,"nullable":true}},"required":["monthly","hourly","license"]},"CapabilityDto":{"type":"object","properties":{"name":{"type":"string","example":"resize"},"enabled":{"type":"boolean","example":true}},"required":["name","enabled"]},"InstancePlanDto":{"type":"object","properties":{"id":{"type":"string","example":"91ca682c-3d92-4a8d-afde-a88d00b7f21e"},"name":{"type":"string","example":"d2-2"},"region":{"type":"string","example":"DE1"},"ram":{"type":"number","example":2},"disk":{"type":"number","example":25},"vcpus":{"type":"number","example":1},"type":{"type":"string","example":"ovh.d2"},"osType":{"type":"string","example":"linux"},"inboundBandwidth":{"type":"number","example":100},"outboundBandwidth":{"type":"number","example":100},"available":{"type":"boolean","example":true},"planCodes":{"$ref":"#/components/schemas/PlanCodesDto"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/CapabilityDto"}},"quota":{"type":"number","example":2}},"required":["id","name","region","ram","disk","vcpus","type","osType","inboundBandwidth","outboundBandwidth","available","planCodes","capabilities","quota"]},"AvailableInstancesResponseDto":{"type":"object","properties":{"regions":{"type":"array","items":{"$ref":"#/components/schemas/RegionInfoDto"}},"vps":{"type":"array","items":{"$ref":"#/components/schemas/InstancePlanDto"}},"baremetal":{"type":"array","items":{"$ref":"#/components/schemas/InstancePlanDto"}}},"required":["regions","vps","baremetal"]},"KvStoragePlanResponseDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"maxDatastores":{"type":"number"},"maxKeysPerDatastore":{"type":"number"},"maxValueSizeBytes":{"type":"number"},"maxTotalStorageBytes":{"type":"string"},"maxBatchKeys":{"type":"number"},"readOpsBurst":{"type":"number"},"readOpsPerMinute":{"type":"number"},"writeOpsBurst":{"type":"number"},"writeOpsPerMinute":{"type":"number"},"priceLix":{"type":"string"},"billingPeriod":{"type":"string"},"includedUsageLix":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","slug","maxDatastores","maxKeysPerDatastore","maxValueSizeBytes","maxTotalStorageBytes","maxBatchKeys","readOpsBurst","readOpsPerMinute","writeOpsBurst","writeOpsPerMinute","priceLix","billingPeriod","includedUsageLix","createdAt","updatedAt"]},"CreateKvSubscriptionDto":{"type":"object","properties":{"serverId":{"type":"string","description":"Server ID to subscribe for KV storage"},"planSlug":{"type":"string","description":"Plan slug (e.g. starter, standard, pro)","example":"starter"}},"required":["serverId","planSlug"]},"KvStorageUsageDto":{"type":"object","properties":{"datastoresCount":{"type":"number"},"totalKeys":{"type":"number"},"totalSizeBytes":{"type":"number"}},"required":["datastoresCount","totalKeys","totalSizeBytes"]},"KvStorageSubscriptionResponseDto":{"type":"object","properties":{"id":{"type":"string"},"subjectType":{"type":"string","enum":["server","instant_world"],"description":"Whether this subscription belongs to a server or an instant world."},"serverId":{"type":"object","description":"Set when subjectType is \"server\"."},"worldId":{"type":"object","description":"Set when subjectType is \"instant_world\"."},"userId":{"type":"string"},"status":{"type":"string"},"plan":{"$ref":"#/components/schemas/KvStoragePlanResponseDto"},"currentPeriodStart":{"format":"date-time","type":"string"},"currentPeriodEnd":{"type":"object"},"nextBillingDate":{"type":"object"},"remainingUsageLix":{"type":"string"},"usageBlockedAt":{"type":"object"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"usage":{"$ref":"#/components/schemas/KvStorageUsageDto"}},"required":["id","subjectType","userId","status","plan","currentPeriodStart","remainingUsageLix","createdAt","updatedAt"]},"UpgradeKvSubscriptionDto":{"type":"object","properties":{"planSlug":{"type":"string","description":"New plan slug to upgrade to","example":"standard"}},"required":["planSlug"]},"CreateDatastoreDto":{"type":"object","properties":{"name":{"type":"string","description":"Datastore name. Alphanumeric, dashes, and underscores only. Max 64 characters.","example":"player-data"}},"required":["name"]},"DatastoreResponseDto":{"type":"object","properties":{"name":{"type":"string"},"keyCount":{"type":"number"},"sizeBytes":{"type":"number"},"createdAt":{"type":"string"}},"required":["name","keyCount","sizeBytes","createdAt"]},"EntryResponseDto":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"object"},"sizeBytes":{"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"version":{"type":"number","description":"Monotonic entry version for optimistic concurrency control.","example":1}},"required":["key","value","sizeBytes","createdAt","updatedAt","version"]},"SetEntryDto":{"type":"object","properties":{"value":{"type":"object","description":"The value to store. Can be any JSON-serializable value (string, number, object, array, boolean).","example":{"score":100,"level":5}},"expectedVersion":{"type":"number","description":"Optional optimistic concurrency version. Use 0 to assert create-only when key does not exist.","example":3}},"required":["value"]},"SetEntryResponseDto":{"type":"object","properties":{"created":{"type":"boolean"},"version":{"type":"number","description":"Monotonic entry version after the write operation.","example":2}},"required":["created","version"]},"BatchGetEntriesDto":{"type":"object","properties":{"keys":{"description":"Keys to fetch in a single request.","maxItems":50,"type":"array","items":{"type":"string"}}},"required":["keys"]},"BatchGetEntriesResponseDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EntryResponseDto"}},"notFound":{"type":"array","items":{"type":"string"}}},"required":["items","notFound"]},"BatchSetEntryItemDto":{"type":"object","properties":{"key":{"type":"string","description":"Entry key","maxLength":128},"value":{"type":"object","description":"JSON-serializable value"},"expectedVersion":{"type":"number","description":"Optional optimistic concurrency version. Use 0 to assert create-only when key does not exist."}},"required":["key","value"]},"BatchSetEntriesDto":{"type":"object","properties":{"items":{"maxItems":50,"type":"array","items":{"$ref":"#/components/schemas/BatchSetEntryItemDto"}},"continueOnError":{"type":"boolean","description":"When true (default), continues processing remaining items even if some fail.","default":true}},"required":["items"]},"BatchSetSuccessItemDto":{"type":"object","properties":{"key":{"type":"string"},"created":{"type":"boolean"},"version":{"type":"number"}},"required":["key","created","version"]},"BatchFailureItemDto":{"type":"object","properties":{"key":{"type":"string"},"code":{"type":"string","description":"Normalized machine-readable error code","example":"VERSION_CONFLICT"},"message":{"type":"string"},"retryAfterMs":{"type":"number"}},"required":["key","code","message"]},"BatchSummaryDto":{"type":"object","properties":{"total":{"type":"number"},"succeeded":{"type":"number"},"failed":{"type":"number"}},"required":["total","succeeded","failed"]},"BatchSetEntriesResponseDto":{"type":"object","properties":{"succeeded":{"type":"array","items":{"$ref":"#/components/schemas/BatchSetSuccessItemDto"}},"failed":{"type":"array","items":{"$ref":"#/components/schemas/BatchFailureItemDto"}},"summary":{"$ref":"#/components/schemas/BatchSummaryDto"}},"required":["succeeded","failed","summary"]},"BatchUpdateEntryItemDto":{"type":"object","properties":{"key":{"type":"string","description":"Entry key","maxLength":128},"patch":{"type":"object","description":"Partial object patch to shallow-merge into existing object value.","example":{"score":200}},"expectedVersion":{"type":"number","description":"Optional optimistic concurrency version."}},"required":["key","patch"]},"BatchUpdateEntriesDto":{"type":"object","properties":{"items":{"maxItems":50,"type":"array","items":{"$ref":"#/components/schemas/BatchUpdateEntryItemDto"}},"continueOnError":{"type":"boolean","description":"When true (default), continues processing remaining items even if some fail.","default":true}},"required":["items"]},"BatchUpdateEntriesResponseDto":{"type":"object","properties":{"succeeded":{"type":"array","items":{"$ref":"#/components/schemas/BatchSetSuccessItemDto"}},"failed":{"type":"array","items":{"$ref":"#/components/schemas/BatchFailureItemDto"}},"summary":{"$ref":"#/components/schemas/BatchSummaryDto"}},"required":["succeeded","failed","summary"]},"BatchDeleteEntryItemDto":{"type":"object","properties":{"key":{"type":"string","description":"Entry key","maxLength":128},"expectedVersion":{"type":"number","description":"Optional optimistic concurrency version."}},"required":["key"]},"BatchDeleteEntriesDto":{"type":"object","properties":{"items":{"maxItems":50,"type":"array","items":{"$ref":"#/components/schemas/BatchDeleteEntryItemDto"}},"continueOnError":{"type":"boolean","description":"When true (default), continues processing remaining items even if some fail.","default":true}},"required":["items"]},"BatchDeleteSuccessItemDto":{"type":"object","properties":{"key":{"type":"string"},"deleted":{"type":"boolean"}},"required":["key","deleted"]},"BatchDeleteEntriesResponseDto":{"type":"object","properties":{"succeeded":{"type":"array","items":{"$ref":"#/components/schemas/BatchDeleteSuccessItemDto"}},"failed":{"type":"array","items":{"$ref":"#/components/schemas/BatchFailureItemDto"}},"summary":{"$ref":"#/components/schemas/BatchSummaryDto"}},"required":["succeeded","failed","summary"]},"AppendLogDto":{"type":"object","properties":{"idempotencyKey":{"type":"string","description":"Idempotency key unique per append intent.","maxLength":128},"entry":{"type":"object","description":"JSON-serializable payload to append as a log event."}},"required":["idempotencyKey","entry"]},"AppendLogResponseDto":{"type":"object","properties":{"key":{"type":"string"},"appendedAt":{"type":"string"},"version":{"type":"number"},"created":{"type":"boolean","description":"False when replayed from idempotency cache.","example":true}},"required":["key","appendedAt","version","created"]},"CreateWorldReviewRequestDto":{"type":"object","properties":{"message":{"type":"string","description":"Review message","maxLength":500,"example":"Loved this world!"},"score":{"type":"number","description":"Score (+1 for thumbs up, -1 for thumbs down)","enum":[1,-1],"example":1}},"required":["score"]},"WorldReviewWithFullUserResponseDto":{"type":"object","properties":{"id":{"type":"string","example":"b1e2c3d4-5678-1234-9abc-1234567890ab"},"worldId":{"type":"string","example":"c1d2e3f4-5678-1234-9abc-1234567890ab"},"message":{"type":"string","example":"Loved this world!"},"score":{"type":"number","example":1},"createdAt":{"format":"date-time","type":"string","example":"2026-07-14T12:34:56.000Z"},"updatedAt":{"format":"date-time","type":"string","example":"2026-07-14T12:34:56.000Z"},"user":{"description":"Full user information of the reviewer","allOf":[{"$ref":"#/components/schemas/UserReviewUserResponseDto"}]}},"required":["id","worldId","score","createdAt","updatedAt","user"]},"WorldReviewsWithThumbsResponseDto":{"type":"object","properties":{"items":{"description":"List of world reviews with full user information","type":"array","items":{"$ref":"#/components/schemas/WorldReviewWithFullUserResponseDto"}},"totalItems":{"type":"number","description":"The total number of items in the collection.","example":100},"pagination":{"description":"The pagination information.","allOf":[{"$ref":"#/components/schemas/PaginationResponseDto"}]},"pageInfo":{"description":"Keyset/cursor pagination info for infinite scroll.","allOf":[{"$ref":"#/components/schemas/PageInfoResponseDto"}]},"thumbsUpPercentage":{"type":"string","example":"80%","description":"Percentage of thumbs up reviews."},"thumbsUpCount":{"type":"number","example":42,"description":"Total thumbs-up votes."},"thumbsDownCount":{"type":"number","example":8,"description":"Total thumbs-down votes."},"totalReviews":{"type":"number","example":50,"description":"Total votes cast on this world."},"userReview":{"description":"The requesting user's own review for this world (if it exists).","nullable":true,"allOf":[{"$ref":"#/components/schemas/WorldReviewWithFullUserResponseDto"}]}},"required":["items","totalItems","pagination","thumbsUpPercentage","thumbsUpCount","thumbsDownCount","totalReviews"]},"UpdateWorldReviewRequestDto":{"type":"object","properties":{"message":{"type":"string","description":"Review message","maxLength":500,"example":"Updated my thoughts!"},"score":{"type":"number","description":"Score (+1 for thumbs up, -1 for thumbs down)","enum":[1,-1],"example":1}}},"TagResponseDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the tag.","example":"Roleplay"}},"required":["name"]},"CreateSubscriptionDto":{"type":"object","properties":{}},"HomeRuntimeLaunchAssignmentResponseDto":{"type":"object","properties":{"assignment":{"type":"string"},"expiresAt":{"type":"string"},"runtimeAdapter":{"type":"string","enum":["unreal"]},"home":{"type":"object"},"runtime":{"type":"object"}},"required":["assignment","expiresAt","runtimeAdapter","home","runtime"]},"CreateHomeRequestDto":{"type":"object","properties":{"slug":{"type":"string","description":"Stable public slug for the home.","example":"jacks-loft"},"title":{"type":"string","example":"Jack's Loft"},"description":{"type":"object","nullable":true},"visibility":{"type":"string","enum":["draft","private","friends","unlisted","public"],"default":"private"},"category":{"type":"string","enum":["apartment","social_room","showroom","event_space","storefront","gallery","game_room","creator_hub","other"],"default":"apartment"},"contentRating":{"type":"string","default":"unrated"},"contentRatingAttestationAccepted":{"type":"boolean","description":"Required when creating a published/discoverable home: confirms the selected content rating is truthful."},"baseTemplateId":{"type":"object","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"previewImageUrl":{"type":"object","nullable":true},"metadata":{"type":"object"}},"required":["slug","title"]},"HomeSlotsResponseDto":{"type":"object","properties":{"used":{"type":"number","description":"Homes you are LIVING IN. Not homes owned — ownership is unlimited."},"locked":{"type":"number","description":"Preserved residences locked after a downgrade. They do not consume a slot."},"limit":{"type":"number","description":"How many you may live in at once on this tier."},"tier":{"type":"string","enum":["free","plus","gold","diamond"]},"nextTier":{"type":"string","enum":["free","plus","gold","diamond"],"nullable":true,"description":"Null on the top tier."},"nextTierLimit":{"type":"object","nullable":true,"description":"Null on the top tier."}},"required":["used","locked","limit","tier","nextTier","nextTierLimit"]},"SlugAvailabilityResponseDto":{"type":"object","properties":{"slug":{"type":"string"},"available":{"type":"boolean"},"suggestion":{"type":"object","nullable":true,"description":"A free alternative. Always present when `available` is false."}},"required":["slug","available","suggestion"]},"MoveIntoHomeRequestDto":{"type":"object","properties":{"shellInventoryItemId":{"type":"string","description":"The owned home-shell instance to move into. Moving into a shell you have lived in before reopens that same residence — slug, title, visitors and saved layout intact."},"moveOutResidenceId":{"type":"string","description":"An active residence to leave in the same transaction when no slot is free. When the destination is locked after a downgrade, the two homes swap active state and both keep every placed prop."},"title":{"type":"string","description":"Title for a residence being opened for the FIRST time. Ignored when moving back into one you already have."},"slug":{"type":"string","description":"Slug for a residence being opened for the first time. Globally unique; one is derived from the title when omitted. Check with GET /api/v1/homes/slug-available first."}},"required":["shellInventoryItemId"]},"MoveOutResponseDto":{"type":"object","properties":{"home":{"$ref":"#/components/schemas/HomeResponseDto"},"releasedItemCount":{"type":"number","description":"Items handed back to your inventory. The confirm sheet names this number BEFORE the user commits — \"47 items will go back to your inventory\" — which is what makes moving out read as a move, not a loss."},"layoutSaved":{"type":"boolean","description":"The layout was saved. Move back in and Restore Layout puts everything you still own back where it was."}},"required":["home","releasedItemCount","layoutSaved"]},"UnavailableRestoreItemDto":{"type":"object","properties":{"itemId":{"type":"string"},"whereItIsNow":{"type":"string","description":"Where it went: inventory | another_home | a_world | listed_for_sale | lived_in | no_longer_owned."}},"required":["itemId","whereItIsNow"]},"RestoreLayoutResponseDto":{"type":"object","properties":{"home":{"$ref":"#/components/schemas/HomeResponseDto"},"restored":{"type":"number","description":"Items put back exactly where they were."},"unavailable":{"description":"Items in the saved layout that are somewhere else now. Reported, never fatal — a restore does not fail because you sold a lamp.","type":"array","items":{"$ref":"#/components/schemas/UnavailableRestoreItemDto"}}},"required":["home","restored","unavailable"]},"ReleaseItemsResponseDto":{"type":"object","properties":{"home":{"$ref":"#/components/schemas/HomeResponseDto"},"released":{"type":"number","description":"Items returned to your inventory."}},"required":["home","released"]},"HomeInviteResponseDto":{"type":"object","properties":{"id":{"type":"string"},"homeId":{"type":"string"},"inviterId":{"type":"string"},"recipientId":{"type":"string"},"status":{"type":"string","enum":["active","revoked"]},"message":{"type":"object","nullable":true},"revokedAt":{"type":"object","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","homeId","inviterId","recipientId","status","message","revokedAt","createdAt","updatedAt"]},"CreateHomeInviteRequestDto":{"type":"object","properties":{"recipientUserId":{"type":"string","description":"User id to invite into this home."},"message":{"type":"object","nullable":true}},"required":["recipientUserId"]},"CastHomeVoteRequestDto":{"type":"object","properties":{"score":{"type":"number","description":"Vote score (+1 for thumbs up / like, -1 for thumbs down / dislike)","enum":[1,-1],"example":1}},"required":["score"]},"UpdateHomeRequestDto":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"object","nullable":true},"visibility":{"type":"string","enum":["draft","private","friends","unlisted","public"]},"category":{"type":"string","enum":["apartment","social_room","showroom","event_space","storefront","gallery","game_room","creator_hub","other"]},"contentRating":{"type":"string"},"contentRatingAttestationAccepted":{"type":"boolean","description":"Required when making a home public/friends/unlisted or changing its rating."},"baseTemplateId":{"type":"object","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"previewImageUrl":{"type":"object","nullable":true},"metadata":{"type":"object"},"isDefault":{"type":"boolean","description":"Make this the default home. Clears the previous default in the same transaction. Only a home you are living in can be the default. `false` is ignored — a default is chosen, never merely un-chosen."},"slotIndex":{"type":"number","description":"Reorder this home in the slot list. Swaps with whichever of your homes currently holds the position.","minimum":0,"maximum":99}}},"PlaceHomeItemRequestDto":{"type":"object","properties":{"itemId":{"type":"string"},"inventoryItemId":{"type":"object","nullable":true},"transform":{"type":"object","description":"Engine-agnostic transform data such as position, rotation, and scale."},"state":{"type":"object"},"metadata":{"type":"object"}},"required":["itemId","transform"]},"UpdateHomePlacementRequestDto":{"type":"object","properties":{"transform":{"type":"object"},"state":{"type":"object"},"metadata":{"type":"object"}}},"CreateHomeSessionRequestDto":{"type":"object","properties":{"liveInviteId":{"type":"string","description":"Recipient-bound live invite id."}}},"InstantWorldVoiceTokenRequestDto":{"type":"object","properties":{"roomId":{"type":"string","description":"Colyseus room instance id the caller has joined."}},"required":["roomId"]},"CreateHomeLiveInviteRequestDto":{"type":"object","properties":{"recipientUserId":{"type":"string","description":"Exact friend account receiving this pass."},"roomId":{"type":"string","description":"Exact live Home instance to join."}},"required":["recipientUserId","roomId"]},"CreateInstantWorldRequestDto":{"type":"object","properties":{"title":{"type":"string","description":"Display name shown on the world page and in listings.","minLength":1,"maxLength":80,"example":"Neon Rooftop Chase"},"description":{"type":"string","description":"Short world description shown in discovery. Also the home for license/attribution text. Optional.","maxLength":1000,"example":"A neon rooftop parkour chase. Music CC-BY by Foo."},"slug":{"type":"string","description":"URL identifier: 3-50 chars, lowercase letters, digits and hyphens (no leading/trailing hyphen). Globally unique.","example":"neon-rooftop-chase"},"serverCreationPermission":{"type":"string","description":"Who may stand up a persistent server for this world. Defaults to `anyone`. Settable at creation so a creator who wants a closed world never has a window where it is open (create-then-PATCH would leave one).","enum":["creator","collaborators","anyone","nobody"],"default":"anyone","example":"anyone"}},"required":["title","slug"]},"PublicInventoryAssetFileResponseDto":{"type":"object","properties":{"size":{"type":"number"},"mimeType":{"type":"object","nullable":true},"url":{"type":"string"}},"required":["size","mimeType","url"]},"PublicInventoryAssetResponseDto":{"type":"object","properties":{"id":{"type":"string"},"rendition":{"type":"string"},"cdnUrl":{"type":"string"},"mimeType":{"type":"string"},"status":{"type":"string"},"engineVersion":{"type":"object","nullable":true},"targetPlatforms":{"type":"array","items":{"type":"string"}},"files":{"type":"array","items":{"$ref":"#/components/schemas/PublicInventoryAssetFileResponseDto"}}},"required":["id","rendition","cdnUrl","mimeType","status","engineVersion","targetPlatforms","files"]},"PublicInventoryUniversalItemResponseDto":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"object","nullable":true},"creator":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/UniversalItemCreatorResponseDto"}]},"creatorId":{"type":"object","nullable":true},"collectibleId":{"type":"object","nullable":true},"kind":{"type":"string"},"category":{"type":"string"},"subCategory":{"type":"object","nullable":true},"slot":{"type":"object","nullable":true},"slotType":{"type":"object","nullable":true},"fits":{"type":"object"},"hostKind":{"type":"object","nullable":true},"surfaceDigest":{"type":"object","nullable":true},"slotCount":{"type":"number"},"badges":{"type":"object"},"genders":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"usage":{"type":"string"},"status":{"type":"string"},"contentRating":{"type":"string"},"priceLix":{"type":"object","nullable":true},"marketplaceDistributions":{"description":"Live Marketplace acquisition routes for this item (CH-1671-followup). This is the field a buy CTA on the item detail/marketplace page reads for every caller who is NOT the creator — omitting it here (as this DTO originally did) made every non-creator viewer's item detail page look unpurchasable regardless of actual availability.","type":"array","items":{"$ref":"#/components/schemas/UniversalItemMarketplaceDistributionResponseDto"}},"isGiftable":{"type":"boolean"},"isCollectible":{"type":"boolean"},"maxOwnablePerUser":{"type":"object","nullable":true},"supply":{"type":"object","nullable":true},"mintedCount":{"type":"object","nullable":true},"properties":{"type":"object"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/PublicInventoryAssetResponseDto"}},"viewCount":{"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","slug","title","description","creator","creatorId","collectibleId","kind","category","subCategory","slot","slotType","fits","hostKind","surfaceDigest","slotCount","badges","genders","tags","usage","status","contentRating","priceLix","marketplaceDistributions","isGiftable","isCollectible","maxOwnablePerUser","supply","mintedCount","properties","assets","viewCount","createdAt","updatedAt"]},"WorldInstanceResponseDto":{"type":"object","properties":{"instanceId":{"type":"string","description":"Room instance id (the Colyseus roomId)."},"currentPlayers":{"type":"number","description":"Players currently connected to this instance."},"maxPlayers":{"type":"number","description":"Player capacity of this instance."},"locked":{"type":"boolean","description":"Whether the instance currently rejects new joins."},"createdAt":{"type":"object","description":"Instance creation time (ISO 8601), when known.","nullable":true}},"required":["instanceId","currentPlayers","maxPlayers","locked","createdAt"]},"UpdateInstantWorldRequestDto":{"type":"object","properties":{"title":{"type":"string","description":"New display name.","minLength":1,"maxLength":80},"description":{"type":"string","description":"New world description (discovery blurb / license / attribution). Send an empty string to clear it.","maxLength":1000},"status":{"type":"string","description":"New lifecycle status.","enum":["draft","published","unlisted"]},"contentRating":{"type":"string","description":"Required when publishing: creator-selected UGC maturity rating.","enum":["everyone","teen","mature","adult"]},"contentRatingAttestationAccepted":{"type":"boolean","description":"Required when publishing: confirms the selected content rating is truthful."},"category":{"type":"string","description":"Editorial category.","enum":["game","store","art","social","home","showcase","other"]},"tags":{"description":"Lightweight editorial/discovery tags. Up to 10 tags, 32 chars each.","maxItems":10,"type":"array","items":{"type":"string"}},"serverCreationPermission":{"type":"string","description":"Who may stand up a persistent server for this world (CH-979 R9c). Defaults to creator-only.","enum":["creator","collaborators","anyone","nobody"]}}},"InstantWorldUploadTicketDto":{"type":"object","properties":{"path":{"type":"string","description":"Bundle-relative file path."},"url":{"type":"string","description":"Presigned PUT URL. ContentLength and ContentType are bound into the signature."},"contentType":{"type":"string","description":"Content-Type the client must send on the PUT."},"cacheControl":{"type":"string","description":"Cache-Control the client must send on the PUT (part of the signature)."}},"required":["path","url","contentType","cacheControl"]},"CreateInstantWorldBuildResponseDto":{"type":"object","properties":{"buildId":{"type":"string","description":"The created build id."},"buildNumber":{"type":"number","description":"Sequential build number within the world."},"uploads":{"description":"Presigned upload tickets — one per declared file.","type":"array","items":{"$ref":"#/components/schemas/InstantWorldUploadTicketDto"}}},"required":["buildId","buildNumber","uploads"]},"InstantWorldBundleFileDto":{"type":"object","properties":{"path":{"type":"string","description":"Bundle-relative file path (no \"..\", no leading \"/\"). E.g. index.html or assets/sprite.png","example":"index.html"},"size":{"type":"number","description":"Exact file size in bytes — bound into the presigned upload.","minimum":1,"maximum":26214400,"example":4096}},"required":["path","size"]},"CreateInstantWorldBuildRequestDto":{"type":"object","properties":{"manifest":{"type":"object","description":"The world manifest (helix.json). Validated and normalized by @hypersoniclabs/helix-manifest in the service — schema errors there are richer than class-validator could express.","additionalProperties":true},"files":{"description":"The declared bundle files. Every file must be uploaded before finalize.","type":"array","items":{"$ref":"#/components/schemas/InstantWorldBundleFileDto"}}},"required":["manifest","files"]},"FinalizeInstantWorldBuildResponseDto":{"type":"object","properties":{"buildId":{"type":"string","description":"The activated build id."},"buildNumber":{"type":"number","description":"Build number that was activated."},"status":{"type":"string","description":"Build status after finalize (active)."},"slug":{"type":"string","description":"World slug."},"bundleSizeBytes":{"type":"number","description":"Total verified bundle size in bytes."},"vaultAssetsUsed":{"type":"number","description":"How many Vault assets this bundle references. Derived by scanning the published manifest — the set that now counts toward each asset’s \"used in N published worlds\"."},"vaultAssetsRemoved":{"type":"number","description":"How many Vault assets the PREVIOUS build referenced and this one does not. Detected by ABSENCE — nothing has to report a removal, so nothing can forget to."},"contentRatingRaised":{"type":"object","nullable":true,"description":"Set when the world’s declared rating was BELOW the highest rating among the Vault assets it uses, and was raised to meet that floor. Surfaced here rather than applied silently: the creator sees what changed, which assets forced it, and can dispute it through the normal report path. Null when no raise was needed. A raise never LOWERS a creator’s own declaration."}},"required":["buildId","buildNumber","status","slug","bundleSizeBytes","vaultAssetsUsed","vaultAssetsRemoved","contentRatingRaised"]},"WorldMediaUploadTicketDto":{"type":"object","properties":{"key":{"type":"string","description":"R2 object key the client must send back to finalize after uploading."},"url":{"type":"string","description":"Presigned PUT URL. ContentLength and ContentType are bound into the signature."},"contentType":{"type":"string","description":"Content-Type the client must send on the PUT."},"cacheControl":{"type":"string","description":"Cache-Control the client must send on the PUT (part of the signature)."},"kind":{"type":"string","description":"Which media slot this upload fills.","enum":["thumbnail","preview"]}},"required":["key","url","contentType","cacheControl","kind"]},"WorldMediaUploadRequestDto":{"type":"object","properties":{"contentType":{"type":"string","description":"MIME type of the file to upload (e.g. image/png).","example":"image/png"},"size":{"type":"number","description":"Exact byte size of the file. Bound into the presigned PUT.","example":245123},"kind":{"type":"string","description":"Which media slot to set. Defaults to 'thumbnail' (the card image).","enum":["thumbnail","preview"],"default":"thumbnail"}},"required":["contentType","size"]},"WorldMediaFinalizeRequestDto":{"type":"object","properties":{"key":{"type":"string","description":"The R2 object key returned by the upload presign step, now uploaded."},"kind":{"type":"string","description":"Which media slot this key fills. Defaults to 'thumbnail'. Must match the kind used at presign time.","enum":["thumbnail","preview"],"default":"thumbnail"}},"required":["key"]},"WorldYoutubeRequestDto":{"type":"object","properties":{"url":{"type":"string","description":"A YouTube link in any usual shape — https://www.youtube.com/watch?v=ID, https://youtu.be/ID, /embed/ID, /shorts/ID, /live/ID — or a bare 11-character video id. Non-YouTube URLs are rejected.","example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}},"required":["url"]},"InstantWorldSessionUserDto":{"type":"object","properties":{"id":{"type":"string","description":"Player user id."},"username":{"type":"string","description":"Player username."},"displayName":{"type":"object","description":"Player display name.","nullable":true}},"required":["id","username","displayName"]},"InstantWorldSessionWorldDto":{"type":"object","properties":{"id":{"type":"string","description":"World id."},"slug":{"type":"string","description":"World slug."},"title":{"type":"string","description":"World title."}},"required":["id","slug","title"]},"InstantWorldSessionResponseDto":{"type":"object","properties":{"token":{"type":"string","description":"Short-lived, world-scoped session token (HS384)."},"expiresAt":{"type":"string","description":"ISO expiry timestamp."},"scopes":{"description":"Granted scopes, derived from the world manifest permissions.","type":"array","items":{"type":"string"}},"user":{"$ref":"#/components/schemas/InstantWorldSessionUserDto"},"world":{"$ref":"#/components/schemas/InstantWorldSessionWorldDto"}},"required":["token","expiresAt","scopes","user","world"]},"InstantWorldRoomJoinResponseDto":{"type":"object","properties":{"wsUrl":{"type":"string","description":"WebSocket URL of the Colyseus room server/cluster."},"roomName":{"type":"string","description":"Colyseus room name to joinOrCreate."},"credential":{"type":"string","description":"Short-lived room credential (HMAC JWT, aud \"helix-instant-room\") the room verifies."},"buildId":{"type":"string","description":"Active build id — the matchmaking filter (players group per build)."},"expiresAt":{"type":"string","description":"ISO expiry timestamp of the credential."}},"required":["wsUrl","roomName","credential","buildId","expiresAt"]},"InstantWorldVoiceTokenResponseDto":{"type":"object","properties":{"livekitUrl":{"type":"string","description":"LiveKit server URL (ws/wss) the SDK connects to."},"token":{"type":"string","description":"LiveKit access token (identity = platform userId)."},"expiresAt":{"type":"string","description":"ISO expiry timestamp of the token."}},"required":["livekitUrl","token","expiresAt"]},"RuntimeLaunchArtifactResponseDto":{"type":"object","properties":{"key":{"type":"string"},"size":{"type":"number"},"sha256":{"type":"string"}},"required":["key","size","sha256"]},"RuntimeLaunchAssignmentResponseDto":{"type":"object","properties":{"assignmentId":{"type":"string"},"instanceId":{"type":"string"},"status":{"type":"string","enum":["allocating","ready"]},"retryAfterMs":{"type":"number"},"assignment":{"type":"object"},"runtimeAdapter":{"type":"string","enum":["unreal"]},"world":{"type":"object"},"build":{"type":"object"},"activity":{"type":"object"},"runtime":{"type":"object"},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/RuntimeLaunchArtifactResponseDto"}}},"required":["assignmentId","instanceId","status","runtimeAdapter","world","build","activity","runtime","artifacts"]},"CreateRuntimeLaunchRequestDto":{"type":"object","properties":{"activityId":{"type":"string","description":"Manifest activity identifier. Omit to launch the default activity.","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$","maxLength":64,"example":"default"},"clientConnectionId":{"type":"string","description":"Client-generated connection identifier bound into the launch assignment.","format":"uuid","example":"11111111-1111-4111-8111-111111111111"},"idempotencyKey":{"type":"string","description":"Caller-stable key used to make retries return the same launch reservation.","minLength":1,"maxLength":128,"example":"launch-11111111-1111-4111-8111-111111111111"}},"required":["clientConnectionId","idempotencyKey"]},"SharedRuntimeArtifactUploadDto":{"type":"object","properties":{"role":{"type":"string"},"path":{"type":"string"},"url":{"type":"string"},"contentType":{"type":"string"},"cacheControl":{"type":"string"},"contentLength":{"type":"number"},"expiresAt":{"type":"string"}},"required":["role","path","url","contentType","cacheControl","contentLength","expiresAt"]},"CreateSharedRuntimeBuildResponseDto":{"type":"object","properties":{"buildId":{"type":"string"},"buildNumber":{"type":"number"},"status":{"type":"string"},"uploads":{"type":"array","items":{"$ref":"#/components/schemas/SharedRuntimeArtifactUploadDto"}}},"required":["buildId","buildNumber","status","uploads"]},"SharedRuntimeDefinitionDto":{"type":"object","properties":{"engineVersion":{"type":"string","example":"5.8.1"},"runtimeVersion":{"type":"string","example":"1.0.0"},"sdkVersion":{"type":"string","example":"1.0.0"}},"required":["engineVersion","runtimeVersion","sdkVersion"]},"SharedRuntimeActivityDto":{"type":"object","properties":{"id":{"type":"string","example":"default"},"map":{"type":"string","example":"/Game/Maps/Main"},"gameMode":{"type":"string","example":"/Game/GameModes/BP_WorldMode.BP_WorldMode_C"},"maxPlayers":{"type":"number","minimum":1,"maximum":1000,"example":32}},"required":["id","map","maxPlayers"]},"SharedRuntimeArtifactDto":{"type":"object","properties":{"role":{"type":"string","enum":["windows_client_content","linux_server_content","shared_content","lua_client","lua_server","lua_shared","webui"]},"path":{"type":"string","example":"client/content.utoc"},"sizeBytes":{"type":"number","minimum":1,"maximum":68719476736},"sha256":{"type":"string","example":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"mediaType":{"type":"string","example":"application/octet-stream"},"mountPath":{"type":"string","example":"/HelixWorld/"}},"required":["role","path","sizeBytes","sha256","mediaType"]},"SharedRuntimeBuildIntentDto":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"runtimeAdapter":{"type":"string","enum":["unreal"]},"networkMode":{"type":"string","enum":["single_player","listen","managed"]},"runtime":{"$ref":"#/components/schemas/SharedRuntimeDefinitionDto"},"activities":{"type":"array","items":{"$ref":"#/components/schemas/SharedRuntimeActivityDto"}},"capabilities":{"type":"array","items":{"type":"string"}},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/SharedRuntimeArtifactDto"}}},"required":["version","runtimeAdapter","networkMode","runtime","activities","artifacts"]},"CreateSharedRuntimeBuildRequestDto":{"type":"object","properties":{"idempotencyKey":{"type":"string","minLength":1,"maxLength":128},"manifest":{"$ref":"#/components/schemas/SharedRuntimeBuildIntentDto"}},"required":["idempotencyKey","manifest"]},"SharedRuntimeVersionSummaryDto":{"type":"object","properties":{"engineVersion":{"type":"string"},"runtimeVersion":{"type":"string"},"sdkVersion":{"type":"string"}},"required":["engineVersion","runtimeVersion","sdkVersion"]},"SharedRuntimeBuildArtifactSummaryDto":{"type":"object","properties":{"role":{"type":"string"},"count":{"type":"number"},"sizeBytes":{"type":"number"}},"required":["role","count","sizeBytes"]},"SharedRuntimeBuildHistoryItemDto":{"type":"object","properties":{"buildId":{"type":"string"},"buildNumber":{"type":"number"},"buildKind":{"type":"string","enum":["shared_runtime"]},"status":{"type":"string"},"runtimeAdapter":{"type":"string","enum":["unreal"]},"networkMode":{"type":"string","enum":["single_player","listen","managed"]},"runtime":{"$ref":"#/components/schemas/SharedRuntimeVersionSummaryDto"},"artifactCount":{"type":"number"},"bundleSizeBytes":{"type":"number"},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/SharedRuntimeBuildArtifactSummaryDto"}},"manifestDigest":{"type":"object"},"validatedAt":{"type":"object"},"revokedAt":{"type":"object"},"rejectionReason":{"type":"object"},"createdAt":{"format":"date-time","type":"string"},"isActive":{"type":"boolean"}},"required":["buildId","buildNumber","buildKind","status","runtimeAdapter","artifactCount","bundleSizeBytes","artifacts","createdAt","isActive"]},"SharedRuntimeBuildHistoryDto":{"type":"object","properties":{"activeBuildId":{"type":"object"},"items":{"type":"array","items":{"$ref":"#/components/schemas/SharedRuntimeBuildHistoryItemDto"}}},"required":["items"]},"SharedRuntimeBuildReceiptDto":{"type":"object","properties":{"buildId":{"type":"string"},"buildNumber":{"type":"number"},"status":{"type":"string"},"manifestDigest":{"type":"string"},"manifestSignature":{"type":"string"},"manifestSigningKeyId":{"type":"string"},"bundleSizeBytes":{"type":"number"},"promotedAt":{"type":"string"}},"required":["buildId","buildNumber","status","manifestDigest","manifestSignature","manifestSigningKeyId","bundleSizeBytes"]},"PromoteSharedRuntimeBuildRequestDto":{"type":"object","properties":{"visibility":{"type":"string","enum":["private","unlisted","public"]}}},"SharedRuntimeDeliveryArtifactDto":{"type":"object","properties":{"role":{"type":"string"},"path":{"type":"string"},"digest":{"type":"string"},"sizeBytes":{"type":"number"},"mediaType":{"type":"string"},"mountPath":{"type":"string"},"url":{"type":"string"},"expiresAt":{"type":"string"}},"required":["role","path","digest","sizeBytes","mediaType","url","expiresAt"]},"SharedRuntimeBuildDeliveryDto":{"type":"object","properties":{"buildId":{"type":"string"},"manifest":{"type":"object"},"manifestDigest":{"type":"string"},"manifestSignature":{"type":"string"},"manifestSigningKeyId":{"type":"string"},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/SharedRuntimeDeliveryArtifactDto"}}},"required":["buildId","manifest","manifestDigest","manifestSignature","manifestSigningKeyId","artifacts"]},"UniversalItemAssetFileRequestDto":{"type":"object","properties":{"key":{"type":"string","description":"Cooked Unreal package file key/path. Only packaged-game containers are accepted: `.pak`, `.utoc`, and `.ucas`. Raw editor `.uasset` files are rejected.","example":"Wearable/ExampleJacket-Windows.utoc","pattern":"\\.(pak|utoc|ucas)$"},"size":{"type":"number","description":"File size in bytes.","example":1048576,"minimum":0},"mimeType":{"type":"object","nullable":true,"description":"File MIME type."},"sha256":{"type":"object","nullable":true,"description":"OPTIONAL lowercase-hex SHA-256 of this file's bytes. Supply it and finalize re-reads the stored object and REJECTS the finalize (422) if the digest does not match — the only way to tell a complete upload from a truncated one, since `size` is client-declared and is not enforced. Omit it and finalize behaves exactly as before.","example":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","pattern":"^[0-9a-fA-F]{64}$"},"metadata":{"type":"object","default":{},"description":"Arbitrary per-file metadata."}},"required":["key","size"]},"CreateUniversalItemAssetRequestDto":{"type":"object","properties":{"rendition":{"type":"string","enum":["web","unreal","thumbnail","preview","texture","mesh","metadata","home-shell"],"description":"Which build this represents (web GLB, unreal, thumbnail, ...).","example":"web"},"filename":{"type":"string","description":"Web build filename (used only to preserve the extension).","maxLength":255,"example":"neon-lounge-chair.glb"},"mimeType":{"type":"string","description":"Web build MIME type.","maxLength":128,"example":"model/gltf-binary"},"sizeBytes":{"type":"number","default":0,"description":"Web build size in bytes (used to choose single vs multipart upload).","example":204800},"files":{"description":"Cooked files that make up the packaged-game Unreal build. Include at least one `.pak`, one `.utoc`, and one `.ucas`; raw editor `.uasset` files are rejected. The response returns one presigned uploadUrl per file. Presence of `files` marks the asset as Unreal-supporting. Omit for a web-only asset.","type":"array","items":{"$ref":"#/components/schemas/UniversalItemAssetFileRequestDto"}},"engineVersion":{"type":"string","nullable":true,"description":"UNREAL ONLY. Engine version this build was cooked for, so a runtime can refuse a package cooked for the wrong engine. `5.7` is the current HELIX native runtime and cook-pipeline target; this field is compatibility metadata, not the package's file-format version. It defaults to `5.7` (matching Helix 2's `packages.engine_version`) when the rendition is `unreal` and nothing is sent, so an Unreal build never reads \"unknown\". The `x-engine-version` request header OVERRIDES this field, exactly as it does on the package endpoints. Sending it explicitly on a non-`unreal` rendition is rejected (400) — a web GLB has no engine version and a client must not be able to read one off it.","example":"5.7","pattern":"^\\d+\\.\\d+(\\.\\d+)?$"},"targetPlatforms":{"type":"array","description":"UNREAL ONLY. The HELIX runtime currently supports Win64 cooked builds only. Mac, Linux, Android, and IOS uploads are rejected. This is a PLATFORM, not a role — Helix 2's client/server/editor keys are a different axis and do not belong here. Optional; validated when present, and rejected (400) on a non-`unreal` rendition.","example":["Win64"],"items":{"type":"string","enum":["Win64"]}},"metadata":{"type":"object","description":"Free-form metadata stored on the asset build.","example":{"lodCount":2}}},"required":["rendition"]},"CreateUniversalItemRequestDto":{"type":"object","properties":{"editionMode":{"type":"string","enum":["standard","collectible"],"default":"standard","description":"Canonical edition. Standard is unlimited and non-resellable; Collectible is fixed-supply, serialized, and Marketplace-resellable."},"collectibleSupply":{"type":"number","minimum":1,"description":"Required only when editionMode=collectible. This single value selects Collectible in creator tooling."},"slug":{"type":"string","description":"URL-safe unique handle for the item. Lowercased server-side; must be unique across all items.","maxLength":80,"example":"neon-lounge-chair"},"title":{"type":"string","description":"Human-readable display name.","maxLength":100,"example":"Neon Lounge Chair"},"description":{"type":"object","nullable":true,"description":"Optional long description shown on the item page.","example":"A glowing mid-century lounge chair that lights up your room."},"kind":{"type":"string","enum":["wearable","home_item","home_shell","avatar","emote","prop","bundle","achievement","add_on","vehicle"],"description":"What kind of item this is (drives usage + where it can go).","example":"home_item"},"category":{"type":"string","enum":["wearable","jackets","tops","bottoms","footwear","accessories","hair","makeup","body","furniture","decor","lighting","structure","utility","interactable","vehicle","collectible","misc"],"description":"Taxonomy bucket within the kind (e.g. furniture, jackets).","example":"furniture"},"subCategory":{"type":"object","nullable":true,"description":"Optional finer-grained sub-category label.","maxLength":64,"example":"seating"},"slot":{"type":"string","nullable":true,"enum":["Cosmetic.Slot.Clothing.Top","Cosmetic.Slot.Clothing.Bottoms","Cosmetic.Slot.Clothing.Set","Cosmetic.Slot.Clothing.Backpack","Cosmetic.Slot.Clothing.Socks","Cosmetic.Slot.Clothing.Shoes","Cosmetic.Slot.Clothing.Underwear.Top","Cosmetic.Slot.Clothing.Underwear.Bottom","Cosmetic.Slot.Clothing.Underwear.Leg","Cosmetic.Slot.Accessory.Head.Hat","Cosmetic.Slot.Accessory.Face.Mask","Cosmetic.Slot.Accessory.Face.Eyewear","Cosmetic.Slot.Accessory.Neck.Necklace","Cosmetic.Slot.Accessory.Ears.Earrings","Cosmetic.Slot.Accessory.Hands.Gloves","Cosmetic.Slot.Accessory.Hands.Nails","Cosmetic.Slot.Appearance.Hair.Main","Cosmetic.Slot.Appearance.Hair.Facial.Beard","Cosmetic.Slot.Appearance.Hair.Facial.Mustache","Cosmetic.Slot.Appearance.Eyes.Eyebrows","Cosmetic.Slot.Appearance.Eyes.Eyelashes","Cosmetic.Slot.Appearance.Eyes.Iris","Cosmetic.Slot.Appearance.Skin.BodyTattoo","Cosmetic.Slot.Appearance.Skin.FaceTattoo","Cosmetic.Slot.Appearance.Makeup.Lipstick","Cosmetic.Slot.Appearance.Makeup.Eyeliner","Cosmetic.Slot.Appearance.Makeup.Eyeshadow","Cosmetic.Slot.Appearance.Makeup.Blush","Cosmetic.Slot.Body.Head","Cosmetic.Slot.Body.Upper","Cosmetic.Slot.Body.Lower","Cosmetic.Slot.Body.Hands","Cosmetic.Slot.Body.Feet","Cosmetic.Slot.Custom"],"description":"Character-Creator cosmetic slot for a wearable, as a gameplay tag (e.g. \"Cosmetic.Slot.Clothing.Top\"). Set for wearables; must be a known CC slot tag.","example":"Cosmetic.Slot.Clothing.Top"},"emoteCategory":{"type":"string","nullable":true,"enum":["regular","sit","lie"],"default":"regular","description":"Which emote slot family this performance belongs to: \"regular\" (the eight r0..r7 wheel slots), \"sit\" or \"lie\". Only for kind=emote, where it defaults to \"regular\"; rejected for every other kind.","example":"regular"},"genders":{"type":"array","description":"Character-Creator gender(s) this wearable is authored for. REQUIRED for kind=wearable, optional for kind=avatar, rejected for every other kind. A garment that fits every body sends [\"male\",\"female\"] — Unreal requires a gender on EVERY cosmetics entry (accessories and tattoos included) and has no \"fits everyone\" value.","example":["male","female"],"items":{"type":"string","enum":["male","female"]}},"ccGenders":{"readOnly":true,"deprecated":true,"description":"NOT a real field. Declared only so sending it fails loudly instead of being silently dropped by the request whitelist — send `genders`.","type":"array","items":{"type":"string"}},"tags":{"description":"Freeform tags for discovery/search (normalised server-side).","example":["glow","mid-century"],"type":"array","items":{"type":"string"}},"usage":{"type":"string","enum":["wear","place","hold","consume","display","inhabit","install"],"description":"How the item is used: wear / place / hold / consume / display / inhabit / install. Ignored for `home_shell`, which is always `inhabit` (a house cannot be placed inside a house), and for `add_on`, which is always `install` (a spoiler cannot be stood in a living room). Both are pinned server-side rather than defaulted, so a client cannot hand back a placeable usage and reopen the hole.","example":"place"},"contentRating":{"type":"string","enum":["everyone","teen","mature","adult"],"description":"Required creator-selected UGC maturity rating. \"everyone\" is accepted and stored as the canonical general tier.","example":"everyone"},"contentRatingAttestationAccepted":{"type":"boolean","description":"Required truthfulness attestation for the self-selected UGC rating. Must be true.","example":true},"priceLix":{"type":"object","nullable":true,"deprecated":true,"description":"DO NOT SEND. Definitions are unpriced; use an Item Distribution for Claim/Buy policy. Non-null values are rejected.","minimum":0,"example":1500},"keepPersonal":{"type":"boolean","default":false,"description":"Keep this creation PERSONAL (private / for-your-own-use) instead of making the definition public. Personal items are free to keep and equip, with no cap on any tier; no Publish fee is charged.","example":false},"libraryContribution":{"type":"boolean","default":false,"description":"Contribute this asset to the shared creator/agent asset library instead of listing it for sale. A library contribution is PUBLIC and searchable (unlike `keepPersonal`, which is private) and has no sale price. Its first public publication still uses the ordinary server-authoritative Publish fee. Rejected together with `priceLix` — contributing and selling are two different acts.","example":false},"publishFeeLix":{"type":"number","deprecated":true,"description":"DO NOT SEND. The total publication charge is derived server-side from the item `kind`; supplying this field is rejected with 400. Read the current amount from GET /universal-items/publish-config."},"idempotencyKey":{"type":"string","description":"Client-generated idempotency key so a retried publish does not double-charge the Publish fee.","maxLength":128,"example":"publish-2f8c1a4e-1b2c-4d3e-9f0a-1b2c3d4e5f60"},"isGiftable":{"type":"boolean","default":false,"description":"Whether owners may gift instances of this item to others.","example":false},"isCollectible":{"type":"boolean","default":false,"description":"Marks the item as collectible-backed. Collectible items are traded through the collectibles system, not bought here.","example":false},"collectibleId":{"type":"object","nullable":true,"description":"Existing scarce collectible template to link as this universal item subtype.","example":null},"maxOwnablePerUser":{"type":"object","nullable":true,"description":"Per-user ownership cap (null = unlimited).","minimum":1,"example":null},"supply":{"type":"object","nullable":true,"description":"Global supply cap across all users (null = unlimited).","minimum":1,"example":null},"properties":{"type":"object","description":"Free-form creator/gameplay properties.","example":{"emitsLight":true,"lightColor":"#39ff14"}},"resalePolicy":{"type":"string","enum":["after_cooldown","after_sellout"],"default":"after_cooldown"},"metadata":{"type":"object","description":"Free-form system/client metadata stored alongside the item.","example":{"snapSurface":"ground"}},"assets":{"description":"Build(s) to attach. Each entry is a presigned upload intent — the response returns an uploadUrl (web) and one per Unreal file. Bytes are uploaded out-of-band, then confirmed via the finalize endpoint.","type":"array","items":{"$ref":"#/components/schemas/CreateUniversalItemAssetRequestDto"}},"slotType":{"type":"object","nullable":true,"description":"ADD-ONS ONLY. The single opening this add-on occupies, e.g. \"vehicle.exhaust@1\". Must be a published row in the platform slot registry (`GET /api/v1/item-slot-types`). Required for kind=add_on and rejected on every other kind.","example":"vehicle.exhaust@1"},"fits":{"type":"object","description":"ADD-ONS ONLY. The `fits` block: { slotType, requires, only? }. `requires` is MANDATORY and every op target must be a subset of it. `only` can only ever NARROW — an absent `only` means UNIVERSAL."},"ops":{"description":"ADD-ONS ONLY. The bounded op list — the four verbs tune / hide / mount / patch. Validated at publish against `fits.requires` and against the slot type's tune ceiling; a violation is a hard 400 with a JSON pointer at the offending op.","type":"array","items":{"type":"object"}},"hostKind":{"type":"object","nullable":true,"description":"BASES ONLY. What this item HOSTS: `vehicle` (v1 ships the only published board) | `character` | `home` | `world`. Declaring it publishes the stock slot board for that host kind in the same transaction, so add-ons can target this item the moment it exists — no second `PUT :id/slots` call. Rejected on kind=add_on, whose host kind comes from its slot type. Omitted means \"not a host\", which is what every non-vehicle item stays.","example":"vehicle"},"hostSurface":{"type":"object","nullable":true,"description":"BASES ONLY, and only alongside `hostKind`. The MEASURED surface: { sockets, nodes, materialSlots, paths }. Normally omitted — an uploaded GLB carrying a `HELIX_vehicle` manifest supplies its own, measured from the mesh itself. Supply it only when publishing by reference, where there is no mesh for the pipeline to read."}},"required":["slug","title","kind","category","usage","contentRating","contentRatingAttestationAccepted"]},"UniversalItemPublishQuoteRequestDto":{"type":"object","properties":{}},"InventorySummaryEntry":{"type":"object","properties":{"itemId":{"type":"string","description":"The universal item ID.","format":"uuid","example":"b3d1f2a4-5c6d-4e7f-8a9b-0c1d2e3f4a5b"},"owned":{"type":"number","description":"Total active instances owned by the user.","example":3},"inInventory":{"type":"number","description":"Instances currently in the user's inventory (not placed).","example":2},"placed":{"type":"number","description":"Instances currently placed in the user's home.","example":1}},"required":["itemId","owned","inInventory","placed"]},"InventoryItemResponseDto":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"itemId":{"type":"string"},"collectibleInstanceId":{"type":"object","nullable":true},"location":{"type":"object"},"state":{"type":"object"},"acquisitionWorldId":{"type":"object","nullable":true},"serial":{"type":"object","nullable":true},"source":{"type":"string"},"status":{"type":"string"},"metadata":{"type":"object"},"equippedSeconds":{"type":"number","description":"Live in-session equip time for this instance, in whole seconds (Equippable Item Usage Tracking v1): committed accrued time PLUS the elapsed time of any currently-open interval, so a worn item ticks up in real time. Derived server-side; clients render it as an \"X hrs worn\" stat. The raw committed counter is under state.equipped_seconds."},"item":{"$ref":"#/components/schemas/UniversalItemResponseDto"},"acquiredAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","userId","itemId","collectibleInstanceId","location","state","acquisitionWorldId","serial","source","status","metadata","equippedSeconds","item","acquiredAt","updatedAt"]},"PublicInventoryItemResponseDto":{"type":"object","properties":{"id":{"type":"string"},"itemId":{"type":"string"},"serial":{"type":"object","nullable":true},"state":{"type":"object"},"item":{"$ref":"#/components/schemas/PublicInventoryUniversalItemResponseDto"},"acquiredAt":{"format":"date-time","type":"string"}},"required":["id","itemId","serial","state","item","acquiredAt"]},"EquippedAvatarResponseDto":{"type":"object","properties":{"source":{"type":"string","enum":["equipped","auto","default"],"description":"Where the avatar came from: \"equipped\" = the user's chosen avatar; \"auto\" = no avatar was equipped so the first owned one was auto-equipped and persisted; \"default\" = nothing equipped — the platform default avatar when itemId/glbUrl are set, else the client default body."},"inventoryItemId":{"type":"object","nullable":true,"description":"The equipped inventory instance id, or null when source is \"default\"."},"itemId":{"type":"object","nullable":true,"description":"The resolved universal item id — for \"default\" this is the platform default avatar item, or null when none is published."},"glbUrl":{"type":"object","nullable":true,"description":"The web (browser GLB) rendition CDN URL. Null when no avatar is owned, or when the resolved avatar has no usable web asset — clients fall back to a default body."},"contentHash":{"type":"object","nullable":true,"description":"Server-verified lowercase SHA-256 of the exact public GLB bytes. Null for the bundled default body and legacy assets without a durable public-object receipt."},"skeleton":{"type":"object","nullable":true,"description":"Best-effort skeleton identifier of the resolved avatar (from asset/item metadata), informational for runtimes that retarget animation. Null when unknown."}},"required":["source","inventoryItemId","itemId","glbUrl","contentHash","skeleton"]},"UpdateAvatarLoadoutRequestDto":{"type":"object","properties":{"baseShape":{"type":"string","enum":["male","female","custom"],"description":"Derived, not stored. `male`/`custom` are accepted but set nothing — change the body through `customAvatarInventoryItemId`. `female` is rejected (no base mesh)."},"customAvatarInventoryItemId":{"type":"object","nullable":true,"description":"Inventory instance id for a custom full-mesh avatar. Null clears the custom avatar."},"equippedSlots":{"type":"object","description":"Map of Cosmetic.Slot.* tag to inventory instance id. Null unequips that slot. The legacy camelCase slot names are still accepted (deprecated) and are mapped to their CC tag; the response always returns CC tags. An item can only be equipped into its own declared slot.","example":{"Cosmetic.Slot.Clothing.Top":"43a3d7cc-9344-4c6a-a9fd-6e2cde18a544","Cosmetic.Slot.Clothing.Shoes":null}}}},"EmoteLoadoutResponseDto":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"slots":{"type":"object","description":"The ten emote slots (r0..r7, sit, lie). An empty slot is null. Only published items the caller still owns appear here — the same gate the public endpoint applies, so what you see is what others see."},"inventory":{"description":"Equippable emote instances the caller owns. Duplicate owned instances are returned as separate rows.","type":"array","items":{"$ref":"#/components/schemas/InventoryItemResponseDto"}}},"required":["version","slots","inventory"]},"UpdateEmoteLoadoutRequestDto":{"type":"object","properties":{"slots":{"type":"object","description":"Map of emote slot to inventory instance id. Null empties that slot. Valid slots: r0, r1, r2, r3, r4, r5, r6, r7, sit, lie.","example":{"r0":"43a3d7cc-9344-4c6a-a9fd-6e2cde18a544","sit":null}}},"required":["slots"]},"EquippedEmoteRolesResponseDto":{"type":"object","properties":{"joinerClip":{"type":"string","description":"HTTPS CDN URL of the joiner's animation GLB, resolved exactly like the initiator clip."},"offsetX":{"type":"number","description":"Metres along the initiator's right."},"offsetZ":{"type":"number","description":"Metres along the initiator's facing."},"offsetYawDeg":{"type":"number","description":"The joiner's own yaw, degrees in [-180, 180]."},"offerAtS":{"type":"number","description":"Seconds into the INITIATOR's clip: the pose they wind up to and hold while waiting for a partner. 0 (the first frame) when the definition authors none or authors junk — the offer instant never costs the pair."}},"required":["joinerClip","offsetX","offsetZ","offsetYawDeg","offerAtS"]},"EquippedEmoteResponseDto":{"type":"object","properties":{"slot":{"type":"string","enum":["r0","r1","r2","r3","r4","r5","r6","r7","sit","lie"],"example":"r0"},"itemId":{"type":"string","description":"The universal item id behind this slot."},"clip":{"type":"string","description":"HTTPS CDN URL of the animation GLB, resolved from the pinned definition."},"playback":{"type":"string","enum":["oneshot","loop"]},"audio":{"type":"string","description":"The definition's first audio reference, resolved the same way the clip is. Absent when the definition declares none or the reference does not resolve — audio never costs an emote its slot."},"label":{"type":"string","description":"The item title as a wheel may draw it: plain text, control characters stripped, trimmed, at most 64 characters. Absent when it sanitizes to nothing."},"roles":{"description":"PAIRED emotes only: the second role another player joins. Absent on a solo emote, on a posture slot, and whenever the joiner clip does not resolve — a broken pair still plays solo, so it never costs the slot.","allOf":[{"$ref":"#/components/schemas/EquippedEmoteRolesResponseDto"}]},"intro":{"type":"string","description":"The ENTER transition GLB played into the clip, resolved the same way it is. Absent when the definition authors none or the reference does not resolve — a transition never costs an emote its slot."},"outro":{"type":"string","description":"The EXIT transition GLB played out of the clip, resolved the same way it is. Absent under the same rules as `intro`."}},"required":["slot","itemId","clip","playback"]},"EquippedEmotesResponseDto":{"type":"object","properties":{"emotes":{"type":"array","items":{"$ref":"#/components/schemas/EquippedEmoteResponseDto"}}},"required":["emotes"]},"SyncCollectibleInstanceInventoryRequestDto":{"type":"object","properties":{"idempotencyKey":{"type":"object","description":"Optional idempotency key for this inventory sync event."}}},"UniversalItemStatsResponseDto":{"type":"object","properties":{"itemId":{"type":"string","description":"The item these metrics belong to."},"purchases":{"type":"number","description":"Total units purchased (sum of purchase quantities).","example":42},"uniqueBuyers":{"type":"number","description":"Distinct buyers who purchased at least one unit.","example":37},"revenueLix":{"type":"number","description":"Gross revenue earned from this item, in LIX.","example":63000},"views":{"type":"number","description":"Total detail/preview views (deduped per viewer per day).","example":512},"rating":{"type":"object","description":"Average rating (0-100) if an item rating system exists; null while items have no reviews.","nullable":true,"example":null},"reviewCount":{"type":"number","description":"Number of reviews backing the rating (0 until items get reviews).","example":0},"trend":{"description":"Daily purchase counts for the trailing 7 days, oldest-first (for a sparkline).","example":[0,1,0,3,2,5,4],"type":"array","items":{"type":"number"}}},"required":["itemId","purchases","uniqueBuyers","revenueLix","views","rating","reviewCount","trend"]},"UpdateUniversalItemRequestDto":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"object","nullable":true},"category":{"type":"string","enum":["wearable","jackets","tops","bottoms","footwear","accessories","hair","makeup","body","furniture","decor","lighting","structure","utility","interactable","vehicle","collectible","misc"]},"subCategory":{"type":"object","nullable":true},"slot":{"type":"string","nullable":true,"enum":["Cosmetic.Slot.Clothing.Top","Cosmetic.Slot.Clothing.Bottoms","Cosmetic.Slot.Clothing.Set","Cosmetic.Slot.Clothing.Backpack","Cosmetic.Slot.Clothing.Socks","Cosmetic.Slot.Clothing.Shoes","Cosmetic.Slot.Clothing.Underwear.Top","Cosmetic.Slot.Clothing.Underwear.Bottom","Cosmetic.Slot.Clothing.Underwear.Leg","Cosmetic.Slot.Accessory.Head.Hat","Cosmetic.Slot.Accessory.Face.Mask","Cosmetic.Slot.Accessory.Face.Eyewear","Cosmetic.Slot.Accessory.Neck.Necklace","Cosmetic.Slot.Accessory.Ears.Earrings","Cosmetic.Slot.Accessory.Hands.Gloves","Cosmetic.Slot.Accessory.Hands.Nails","Cosmetic.Slot.Appearance.Hair.Main","Cosmetic.Slot.Appearance.Hair.Facial.Beard","Cosmetic.Slot.Appearance.Hair.Facial.Mustache","Cosmetic.Slot.Appearance.Eyes.Eyebrows","Cosmetic.Slot.Appearance.Eyes.Eyelashes","Cosmetic.Slot.Appearance.Eyes.Iris","Cosmetic.Slot.Appearance.Skin.BodyTattoo","Cosmetic.Slot.Appearance.Skin.FaceTattoo","Cosmetic.Slot.Appearance.Makeup.Lipstick","Cosmetic.Slot.Appearance.Makeup.Eyeliner","Cosmetic.Slot.Appearance.Makeup.Eyeshadow","Cosmetic.Slot.Appearance.Makeup.Blush","Cosmetic.Slot.Body.Head","Cosmetic.Slot.Body.Upper","Cosmetic.Slot.Body.Lower","Cosmetic.Slot.Body.Hands","Cosmetic.Slot.Body.Feet","Cosmetic.Slot.Custom"],"description":"Character-Creator cosmetic slot for a wearable (gameplay tag). Send null to clear. Must be a known CC slot tag."},"emoteCategory":{"type":"string","nullable":true,"enum":["regular","sit","lie"],"description":"Which emote slot family this performance belongs to (\"regular\", \"sit\" or \"lie\"). Omit to leave unchanged; an emote can never be left without one."},"genders":{"type":"array","description":"Character-Creator gender(s) this wearable is authored for. Omit to leave unchanged; a wearable can never be left with an empty set.","example":["male","female"],"items":{"type":"string","enum":["male","female"]}},"ccGenders":{"readOnly":true,"deprecated":true,"description":"NOT a real field. Declared only so sending it fails loudly instead of being silently dropped by the request whitelist — send `genders`.","type":"array","items":{"type":"string"}},"usage":{"type":"string","enum":["wear","place","hold","consume","display","inhabit","install"]},"priceLix":{"type":"object","nullable":true,"deprecated":true,"description":"DO NOT SEND. Definitions are unpriced; update the Item Distribution instead. Any supplied value is rejected."},"isGiftable":{"type":"boolean"},"maxOwnablePerUser":{"type":"object","nullable":true},"supply":{"type":"object","nullable":true},"properties":{"type":"object"},"resalePolicy":{"type":"string","enum":["after_cooldown","after_sellout"]}}},"UpdateUniversalItemAssetRequestDto":{"type":"object","properties":{"rendition":{"type":"string","enum":["web","unreal","thumbnail","preview","texture","mesh","metadata","home-shell"],"description":"Which build this represents (web GLB, unreal, thumbnail, ...).","example":"web"},"filename":{"type":"string","description":"Web build filename (used only to preserve the extension).","maxLength":255,"example":"neon-lounge-chair.glb"},"mimeType":{"type":"string","description":"Web build MIME type.","maxLength":128,"example":"model/gltf-binary"},"sizeBytes":{"type":"number","default":0,"description":"Web build size in bytes (used to choose single vs multipart upload).","example":204800},"files":{"description":"Cooked files that make up the packaged-game Unreal build. Include at least one `.pak`, one `.utoc`, and one `.ucas`; raw editor `.uasset` files are rejected. The response returns one presigned uploadUrl per file. Presence of `files` marks the asset as Unreal-supporting. Omit for a web-only asset.","type":"array","items":{"$ref":"#/components/schemas/UniversalItemAssetFileRequestDto"}},"engineVersion":{"type":"string","nullable":true,"description":"UNREAL ONLY. Engine version this build was cooked for, so a runtime can refuse a package cooked for the wrong engine. `5.7` is the current HELIX native runtime and cook-pipeline target; this field is compatibility metadata, not the package's file-format version. It defaults to `5.7` (matching Helix 2's `packages.engine_version`) when the rendition is `unreal` and nothing is sent, so an Unreal build never reads \"unknown\". The `x-engine-version` request header OVERRIDES this field, exactly as it does on the package endpoints. Sending it explicitly on a non-`unreal` rendition is rejected (400) — a web GLB has no engine version and a client must not be able to read one off it.","example":"5.7","pattern":"^\\d+\\.\\d+(\\.\\d+)?$"},"targetPlatforms":{"type":"array","description":"UNREAL ONLY. The HELIX runtime currently supports Win64 cooked builds only. Mac, Linux, Android, and IOS uploads are rejected. This is a PLATFORM, not a role — Helix 2's client/server/editor keys are a different axis and do not belong here. Optional; validated when present, and rejected (400) on a non-`unreal` rendition.","example":["Win64"],"items":{"type":"string","enum":["Win64"]}},"metadata":{"type":"object","description":"Free-form metadata stored on the asset build.","example":{"lodCount":2}}}},"FinalizeUniversalItemAssetRequestDto":{"type":"object","properties":{"sizeBytes":{"type":"number","description":"Observed size of the WEB build in bytes. Advisory: it is recorded, not enforced.","example":204800,"minimum":0}}},"UniversalItemPurchaseResponseDto":{"type":"object","properties":{"transactionId":{"type":"string","description":"Economy transaction id for the LIX transfer buyer → creator.","example":"e7c9a1b2-3d4e-4f5a-8b6c-7d8e9f0a1b2c"},"quantity":{"type":"number","description":"Number of instances delivered.","example":1},"unitPriceLix":{"type":"number","description":"Unit price paid, in LIX.","example":1500},"totalLix":{"type":"number","description":"Total charged (unit × quantity), in LIX.","example":1500},"inventoryItem":{"description":"The first delivered inventory instance.","allOf":[{"$ref":"#/components/schemas/InventoryItemResponseDto"}]}},"required":["transactionId","quantity","unitPriceLix","totalLix","inventoryItem"]},"PurchaseUniversalItemRequestDto":{"type":"object","properties":{"quantity":{"type":"number","default":1,"minimum":1,"description":"How many instances to buy. Paid total = unit price × quantity; an explicitly free listing grants one active copy per user.","example":1},"idempotencyKey":{"type":"object","nullable":true,"description":"Client-generated key used to safely retry a purchase without double-charging. Mint it ONCE per purchase intent and reuse it for every retry of that intent — a new key per attempt is a second purchase, not a retry. Use an unguessable value (v4 UUID): a key already used by another buyer is rejected with 409. Omitting it makes the purchase non-idempotent and replayable.","maxLength":128,"example":"purchase-9c2e1f7a-3b4c-4d5e-8f90-a1b2c3d4e5f6"},"acquisitionWorldId":{"type":"object","nullable":true,"description":"The instant world the purchase happened in, when bought in-world (attribution).","example":null}},"required":["quantity"]},"UniversalItemSelfMintResponseDto":{"type":"object","properties":{"transactionId":{"type":"object","description":"Economy transaction id for the mint fee creator → platform. Null when the configured fee is 0.","example":"e7c9a1b2-3d4e-4f5a-8b6c-7d8e9f0a1b2c","nullable":true},"feeLix":{"type":"number","description":"Fee paid to the platform for this mint, in LIX. No proceeds are credited back to the creator.","example":75},"serial":{"type":"object","description":"Serial assigned to the new instance for a collectible-backed item; null for a plain item.","example":2,"nullable":true},"inventoryItem":{"description":"The newly minted inventory instance.","allOf":[{"$ref":"#/components/schemas/InventoryItemResponseDto"}]}},"required":["transactionId","feeLix","serial","inventoryItem"]},"SelfMintUniversalItemRequestDto":{"type":"object","properties":{"quantity":{"type":"number","description":"How many copies to mint. Only 1 is supported today — one fee, one serial, one idempotency key.","default":1,"minimum":1,"maximum":1},"idempotencyKey":{"type":"string","description":"Client-supplied idempotency key. Replaying the same key returns the original mint instead of charging again."}}},"PublishPersonalItemRequestDto":{"type":"object","properties":{"priceLix":{"type":"object","nullable":true,"deprecated":true,"description":"DO NOT SEND. Definitions are unpriced; create an Item Distribution after publishing. Any supplied value is rejected.","minimum":0,"maximum":999999999999999},"idempotencyKey":{"type":"string","maxLength":128,"description":"Client-generated publish-intent key. Reuse it when retrying the same publish after a lost response."}}},"DelistUniversalItemRequestDto":{"type":"object","properties":{"reason":{"type":"string","description":"Optional creator-visible note for why this was delisted.","maxLength":500,"example":"Test item, not meant for real distribution."}}},"GiftUniversalItemRequestDto":{"type":"object","properties":{"recipientUserId":{"type":"string","description":"The user who will receive the gifted instance(s).","format":"uuid","example":"33333333-3333-4333-8333-333333333333"},"quantity":{"type":"number","default":1,"minimum":1,"description":"How many owned instances to gift.","example":1},"idempotencyKey":{"type":"object","nullable":true,"description":"Client-generated key used to dedupe gift retries.","maxLength":128,"example":"gift-1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},"reason":{"type":"object","nullable":true,"description":"Optional human-readable reason recorded on the inventory event.","maxLength":128,"example":"Birthday gift"}},"required":["recipientUserId","quantity"]},"ModerateUniversalItemRequestDto":{"type":"object","properties":{"status":{"type":"string","description":"Moderated lifecycle status.","enum":["published","delisted","rejected","suspended"],"example":"delisted"},"contentRating":{"type":"string","description":"Moderated content rating such as everyone, teen, mature, adult.","maxLength":16,"example":"teen"},"contentRatingStatus":{"type":"string","description":"Trust-and-safety review status for the item rating.","enum":["pending_review","approved","flagged","rejected"],"example":"approved"},"reason":{"type":"string","description":"Operator-visible moderation note.","maxLength":1000,"example":"Approved after manual art review."}}},"UpdateItemTagsRequestDto":{"type":"object","properties":{"add":{"description":"Tags to add. Normalised server-side (lowercased/trimmed/deduped) and merged with the tags the item already carries.","example":["avatar-starter","avatar-default"],"type":"array","items":{"type":"string"}},"remove":{"description":"Tags to remove, applied before `add`. Matched case-insensitively; unknown tags are ignored.","example":["avatar-default"],"type":"array","items":{"type":"string"}}}},"GrantInventoryItemRequestDto":{"type":"object","properties":{"userId":{"type":"string","description":"The user to grant the item to.","format":"uuid","example":"33333333-3333-4333-8333-333333333333"},"quantity":{"type":"number","default":1,"minimum":1,"description":"How many instances to grant.","example":1},"source":{"type":"string","enum":["grant","purchase","gift","collectible","world_reward","admin"],"default":"grant","description":"How the recipient acquired the item (for the ledger).","example":"grant"},"sourceWorldId":{"type":"object","nullable":true,"description":"The world this grant originated from, if any (attribution).","example":null},"idempotencyKey":{"type":"object","nullable":true,"description":"Client-generated key so a retried grant is applied once.","maxLength":128,"example":"grant-7f0a1b2c-3d4e-4f5a-8b9c-0d1e2f3a4b5c"},"reason":{"type":"object","nullable":true,"description":"Human-readable reason recorded on the inventory event.","maxLength":128,"example":"Founder reward"}},"required":["userId","quantity","source"]},"PublishSlotBoardRequestDto":{"type":"object","properties":{"hostKind":{"type":"string","description":"vehicle | character | home | world.","example":"vehicle"},"thirdParty":{"type":"string","description":"Board-wide third-party policy. `anyone` (default) | `official` | `grp:<groupId>`. It may be RELAXED after publish and never tightened without a major bump."},"allowlistedGroups":{"description":"Creator-group ids whose members count as `official` on this item. Bare UUIDs — a group HANDLE never reaches a published board.","type":"array","items":{"type":"string"}},"perSlot":{"type":"object","description":"Per-slot narrowing, keyed by slot id: { \"pwr.induction\": { thirdParty, tune, hide, patch } }. Every field can only ever NARROW below the registry ceiling."},"fitted":{"type":"object","description":"What this base ships ALREADY FITTED, keyed by slot INSTANCE id: { \"pwr.exhaust\": \"<add-on item id>\" }. Each value must be a PUBLISHED add-on that actually fits this base in that slot — the same fitment predicate the compose route runs. Removing an entry is not a narrowing change and never needs a major bump.","example":{"pwr.exhaust":"0f6c…"}},"surface":{"type":"object","description":"The MEASURED surface: { sockets, nodes, materialSlots, paths, skeleton }. Emitted by the item pipeline from the real asset — `paths` is the set of tunable paths that expand to at least one site on this base, and it is what the capability proof runs against."},"major":{"type":"boolean","description":"Accept a NARROWING change as a major version bump. Without it a change that removes a slot or narrows a grant is refused, with the count of add-on listings it would affect."}},"required":["hostKind"]},"ValidateFitRequestDto":{"type":"object","properties":{"fits":{"type":"object","description":"The draft `fits` block: { slotType, requires, only? }. `requires` is mandatory."},"ops":{"description":"The draft ops list — tune / hide / mount / patch.","type":"array","items":{"type":"object"}}},"required":["fits"]},"ComposeRequestDto":{"type":"object","properties":{"equip":{"type":"object","description":"slotId → the INVENTORY ITEM ID of an add-on you own, or null to clear the slot. Inventory id, never catalogue id: keying by catalogue id is how one purchase fills N slots.","example":{"pwr.exhaust":"0f6c…","ext.spoiler":null}},"applyBuild":{"type":"string","description":"Apply a saved build first, then the explicit `equip` on top."},"saveAs":{"type":"string","description":"Save the resulting assignment under this name."}}},"CreateCreatorGroupRequestDto":{"type":"object","properties":{"handle":{"type":"string","example":"novastudios"},"displayName":{"type":"string","example":"Nova Studios"}},"required":["handle","displayName"]},"UpdateCreatorGroupRequestDto":{"type":"object","properties":{"handle":{"type":"string"},"displayName":{"type":"string"}}},"InviteCreatorGroupMemberRequestDto":{"type":"object","properties":{"userId":{"type":"string"}},"required":["userId"]},"TransferCreatorGroupRequestDto":{"type":"object","properties":{"userId":{"type":"string"}},"required":["userId"]},"InstantPackageFileDto":{"type":"object","properties":{"path":{"type":"string","description":"Bundle-relative file path.","example":"index.js"},"size":{"type":"number","minimum":1,"maximum":26214400,"example":2048},"checksumSha256":{"type":"string","description":"Lowercase SHA-256 of the file bytes. Required for interactable bundles; optional for legacy package kinds.","pattern":"^[A-Fa-f0-9]{64}$"}},"required":["path","size"]},"CreateInstantPackageVersionRequestDto":{"type":"object","properties":{"manifest":{"type":"object","description":"The platform envelope (kind/slug/version/title/entry/system). Validated by @hypersoniclabs/helix-manifest in the service.","additionalProperties":true},"payload":{"type":"object","description":"The system payload (ability.json) for kind: ability — the discovery documentation. Optional for system/asset-pack.","additionalProperties":true},"files":{"type":"array","items":{"$ref":"#/components/schemas/InstantPackageFileDto"}}},"required":["manifest","files"]},"DeactivateInstantPackageVersionRequestDto":{"type":"object","properties":{"reason":{"type":"string","description":"Why this version is being pulled or restored. Required — this is the audit record.","example":"camera regression on mobile, reported by three worlds","maxLength":500}},"required":["reason"]},"ReactivateInstantPackageVersionRequestDto":{"type":"object","properties":{"reason":{"type":"string","description":"Why this version is being pulled or restored. Required — this is the audit record.","example":"camera regression on mobile, reported by three worlds","maxLength":500},"rolloutPercent":{"type":"number","default":0,"minimum":0,"maximum":100,"description":"Rollout to restore the version at. Defaults to 0 — a version that was pulled goes back STAGED, not straight to every world it broke."}},"required":["reason"]},"SetInstantPackageVersionRolloutRequestDto":{"type":"object","properties":{"rolloutPercent":{"type":"number","description":"Share of worlds this version may resolve to, 0-100. New versions start at 0; promote 1 -> 10 -> 100.","minimum":0,"maximum":100,"example":10},"reason":{"type":"string","maxLength":500,"example":"canary clean for 2h, widening"}},"required":["rolloutPercent","reason"]},"RegisterWorldProductRequestDto":{"type":"object","properties":{"worldId":{"type":"string"},"key":{"type":"object","nullable":true,"description":"Creator-authored stable name, unique within the world and immutable once set. World code buys it as `pkey:<key>`. Lowercase alphanumeric plus - and _."},"title":{"type":"string"},"description":{"type":"object","nullable":true},"priceLix":{"type":"number","description":"Price in LIX. 0 = free (Claim)."},"type":{"type":"string","enum":["consumable","non_consumable","item_grant"],"description":"Legacy authoring: required when grants is not provided; forbidden with grants (the type is derived)."},"itemId":{"type":"object","nullable":true,"description":"UniversalItem granted on purchase. Required for item_grant / non_consumable; omit for consumable and for grants products."},"grants":{"type":"object","nullable":true,"description":"Authored effect array: what the purchase hands over (item | pass | currency; several = bundle, empty = tip jar). Mutually exclusive with type/itemId; immutable once registered. Deep-validated server-side."},"maxPerUser":{"type":"object","nullable":true}},"required":["worldId","title","priceLix"]},"UpdateWorldProductRequestDto":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"object","nullable":true},"priceLix":{"type":"number"},"maxPerUser":{"type":"object","nullable":true},"active":{"type":"boolean"}}},"SetProductActiveRequestDto":{"type":"object","properties":{"active":{"type":"boolean"}},"required":["active"]},"IwpPurchaseRequestDto":{"type":"object","properties":{"ref":{"type":"string","description":"What to buy: a world productId, or `item:<universalItemId>` for a marketplace item."},"worldId":{"type":"string","nullable":true,"description":"The world the purchase is happening in."},"idempotencyKey":{"type":"string","description":"Client-generated key, stable across retries — the replay / double-charge guard."},"displayedPriceLix":{"type":"number","description":"The price the confirm dialog DISPLAYED (the price echo). When present, a mismatch with the authoritative price refuses the purchase as PriceChanged instead of charging a number the player never saw."},"displayedPriceCoins":{"type":"number","description":"The COIN total the confirm dialog DISPLAYED — the price echo for a COINS-priced distribution (HYPR-5026). Same contract as displayedPriceLix: a mismatch refuses as PriceChanged."},"quantity":{"type":"number","default":1,"minimum":1,"maximum":100,"description":"Number of copies to Claim or Buy from an item distribution. The shell re-quotes the authoritative total before confirmation."}},"required":["ref","idempotencyKey"]},"CreatorAnalyticsTotalsDto":{"type":"object","properties":{"grossSalesLix":{"type":"number"},"creatorEarningsLix":{"type":"object","nullable":true,"description":"Settled creator-credit amount when available from economy settlement data."},"completedPurchases":{"type":"number"},"uniqueBuyers":{"type":"number"}},"required":["grossSalesLix","creatorEarningsLix","completedPurchases","uniqueBuyers"]},"CreatorAnalyticsEarningsDto":{"type":"object","properties":{"creatorEarningsLix":{"type":"object","nullable":true,"description":"Null when the main purchase ledger has only gross sale price and economy transaction ids."},"source":{"type":"string","enum":["unavailable_from_purchase_ledger"]}},"required":["creatorEarningsLix","source"]},"CreatorAnalyticsWorldSummaryDto":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"detailPath":{"type":"object","nullable":true},"grossSalesLix":{"type":"number"},"completedPurchases":{"type":"number"}},"required":["id","slug","title","detailPath","grossSalesLix","completedPurchases"]},"CreatorAnalyticsProductSummaryDto":{"type":"object","properties":{"id":{"type":"string"},"worldId":{"type":"string"},"title":{"type":"string"},"type":{"type":"string","enum":["consumable","non_consumable","item_grant"]},"grossSalesLix":{"type":"number"},"completedPurchases":{"type":"number"}},"required":["id","worldId","title","type","grossSalesLix","completedPurchases"]},"CreatorCommerceOverviewResponseDto":{"type":"object","properties":{"totals":{"$ref":"#/components/schemas/CreatorAnalyticsTotalsDto"},"earnings":{"$ref":"#/components/schemas/CreatorAnalyticsEarningsDto"},"topWorld":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorAnalyticsWorldSummaryDto"}]},"topProduct":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorAnalyticsProductSummaryDto"}]}},"required":["totals","earnings","topWorld","topProduct"]},"CreatorAnalyticsTrendPointDto":{"type":"object","properties":{"bucket":{"type":"string"},"grossSalesLix":{"type":"number"},"creatorEarningsLix":{"type":"object","nullable":true},"completedPurchases":{"type":"number"},"uniqueBuyers":{"type":"number"}},"required":["bucket","grossSalesLix","creatorEarningsLix","completedPurchases","uniqueBuyers"]},"CreatorWorldAnalyticsResponseDto":{"type":"object","properties":{"world":{"$ref":"#/components/schemas/CreatorAnalyticsWorldSummaryDto"},"totals":{"$ref":"#/components/schemas/CreatorAnalyticsTotalsDto"},"grain":{"type":"string","enum":["day","week","month"]},"trend":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsTrendPointDto"}},"topProduct":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorAnalyticsProductSummaryDto"}]}},"required":["world","totals","grain","trend","topProduct"]},"CreatorProductAnalyticsResponseDto":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/CreatorAnalyticsProductSummaryDto"},"world":{"$ref":"#/components/schemas/CreatorAnalyticsWorldSummaryDto"},"totals":{"$ref":"#/components/schemas/CreatorAnalyticsTotalsDto"},"grain":{"type":"string","enum":["day","week","month"]},"trend":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsTrendPointDto"}}},"required":["product","world","totals","grain","trend"]},"CreatorPurchaseLedgerWorldDto":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"detailPath":{"type":"object","nullable":true}},"required":["id","slug","title","detailPath"]},"CreatorPurchaseLedgerProductDto":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"object","nullable":true},"type":{"type":"string","enum":["consumable","non_consumable","item_grant"],"nullable":true},"itemId":{"type":"object","nullable":true}},"required":["id","title","description","type","itemId"]},"CreatorPurchaseLedgerItemDto":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"object","nullable":true}},"required":["id","title","slug"]},"CreatorPurchaseLedgerBuyerDto":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"object","nullable":true}},"required":["id","username"]},"CreatorPurchaseLedgerEntryDto":{"type":"object","properties":{"id":{"type":"string"},"idempotencyKey":{"type":"string"},"refType":{"type":"string","enum":["world_product","marketplace_item","item_distribution","collectible_listing"]},"status":{"type":"string","enum":["Pending","Granted","Claimed","AlreadyOwned","InsufficientFunds","MaxPerUserReached","ProductInactive","ProductNotFound","NotInWorld","Unauthorized","RateLimited","Cancelled","Failed","Timeout","PriceChanged"]},"priceLix":{"type":"number"},"creatorEarningsLix":{"type":"object","nullable":true},"economyTransactionId":{"type":"object","nullable":true},"inventoryEventId":{"type":"object","nullable":true},"world":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorPurchaseLedgerWorldDto"}]},"product":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorPurchaseLedgerProductDto"}]},"item":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorPurchaseLedgerItemDto"}]},"buyer":{"$ref":"#/components/schemas/CreatorPurchaseLedgerBuyerDto"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","idempotencyKey","refType","status","priceLix","creatorEarningsLix","economyTransactionId","inventoryEventId","world","product","item","buyer","createdAt","updatedAt"]},"ConsumeEntitlementRequestDto":{"type":"object","properties":{"code":{"type":"string","description":"The named balance to spend (a currency code)."},"amount":{"type":"number","description":"How much to spend. Floor-at-zero: an insufficient balance rejects."},"opId":{"type":"string","description":"Caller-minted operation id, stable across retries — the consume replay guard (a bounded ring)."},"sub":{"type":"string","description":"Room lane only: the player whose balance is spent (the room is authoritative for its seats). A session spends only its own and leaves this out."}},"required":["code","amount","opId"]},"ClaimPurchaseEventRequestDto":{"type":"object","properties":{"purchaseId":{"type":"string","description":"The settled purchase whose DSL event is being claimed."},"sub":{"type":"string","description":"The buyer the receipt names — must match the row."},"claimToken":{"type":"string","description":"Claimant nonce, minted once per receipt by the room and re-sent verbatim on a retry — the same token re-answers claimed:true after a lost response."}},"required":["purchaseId","sub","claimToken"]},"CoinBalanceResponseDto":{"type":"object","properties":{"userId":{"type":"string"},"balance":{"type":"string","description":"Current coin balance as a base-10 integer string.","example":"9007199254740993"},"lifetimeEarned":{"type":"string","description":"Lifetime earned coins as a base-10 integer string.","example":"9007199254740993"},"lifetimeSpent":{"type":"string","description":"Lifetime spent coins as a base-10 integer string.","example":"1000000000000000"},"updatedAt":{"format":"date-time","type":"string"}},"required":["userId","balance","lifetimeEarned","lifetimeSpent","updatedAt"]},"CoinTransactionResponseDto":{"type":"object","properties":{"id":{"type":"string"},"userId":{"type":"string"},"type":{"type":"string"},"amount":{"type":"string","description":"Signed coin amount as a base-10 integer string. Positive credits, negative debits.","example":"-250"},"balanceAfter":{"type":"string","description":"Balance after this transaction as a base-10 integer string.","example":"9007199254740993"},"sourceWorldId":{"type":"object","nullable":true},"idempotencyKey":{"type":"object","nullable":true},"reason":{"type":"object","nullable":true},"metadata":{"type":"object"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","userId","type","amount","balanceAfter","sourceWorldId","idempotencyKey","reason","metadata","createdAt"]},"WorldCoinMutationRequestDto":{"type":"object","properties":{"amount":{"type":"number","description":"Positive safe integer amount of coins.","example":25,"maximum":9007199254740991},"idempotencyKey":{"type":"string","description":"World-generated idempotency key for this gameplay event."},"reason":{"type":"object","nullable":true},"metadata":{"type":"object"}},"required":["amount","idempotencyKey"]},"AdjustCoinsRequestDto":{"type":"object","properties":{"userId":{"type":"string"},"amount":{"type":"number","description":"Positive safe integer amount of coins.","example":100,"maximum":9007199254740991},"sourceWorldId":{"type":"object","nullable":true},"idempotencyKey":{"type":"object","nullable":true},"reason":{"type":"object","nullable":true},"metadata":{"type":"object"}},"required":["userId","amount"]},"DebugCoinMutationRequestDto":{"type":"object","properties":{"amount":{"type":"number","description":"Positive safe integer coin amount.","example":500},"reason":{"type":"object","nullable":true},"metadata":{"type":"object"}},"required":["amount"]},"UpdateWorldCoinAuthorityRequestDto":{"type":"object","properties":{"isOfficial":{"type":"boolean"},"coinEarnEnabled":{"type":"boolean"},"coinSpendEnabled":{"type":"boolean"}},"required":["isOfficial","coinEarnEnabled","coinSpendEnabled"]},"RuntimePresenceActivityDto":{"type":"object","properties":{"state":{"type":"string","description":"Free-form activity line shown to permitted viewers, e.g. \"Racing — lap 3/5\".","example":"Racing — lap 3/5","maxLength":128},"details":{"type":"string","description":"Secondary activity detail line.","maxLength":128},"image":{"type":"string","description":"Custom activity image (asset key or URL). Omit to default to the world thumbnail.","maxLength":300},"party":{"$ref":"#/components/schemas/PresenceActivityPartyDto"},"joinable":{"type":"boolean","description":"Hint that this activity is joinable (gated by MP runtime).","default":false}},"required":["state"]},"CreateItemDistributionRequestDto":{"type":"object","properties":{"itemId":{"type":"string","format":"uuid"},"channel":{"type":"string","enum":["marketplace","world"]},"worldId":{"type":"string","format":"uuid"},"key":{"type":"string","maxLength":64,"example":"harbor-postcard"},"priceLix":{"type":"number","minimum":0,"description":"0 is Claim; a positive value must meet the item category floor."},"currency":{"type":"string","enum":["LIX","COINS"],"default":"LIX","description":"COINS sells for the soft currency (HYPR-5026): the route must carry priceCoins and keep priceLix at 0. Coin purchases debit the buyer and credit no one."},"priceCoins":{"type":"number","minimum":0},"active":{"type":"boolean","default":true},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"maxPerPlayer":{"type":"object","minimum":1},"maxClaims":{"type":"number","minimum":1}},"required":["itemId","channel","priceLix"]},"UpdateItemDistributionRequestDto":{"type":"object","properties":{"priceLix":{"type":"number","minimum":0},"active":{"type":"boolean"},"startsAt":{"type":"object","format":"date-time","nullable":true},"endsAt":{"type":"object","format":"date-time","nullable":true},"maxPerPlayer":{"type":"object","minimum":1,"nullable":true},"maxClaims":{"type":"object","minimum":1,"nullable":true}}},"InstantBuyRequestDto":{"type":"object","properties":{"listingId":{"type":"string","description":"ID of the listing to purchase","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"idempotencyKey":{"type":"string","description":"Client-generated key used to safely retry an instant-buy without double-charging. Mint it ONCE per purchase intent and reuse it for every retry of that intent — a new key per attempt is a second purchase, not a retry. Use an unguessable value (v4 UUID): a key already used by another buyer is rejected with 409. Omitting it makes the purchase non-idempotent and replayable.","maxLength":128,"example":"instant-buy-9c2e1f7a-3b4c-4d5e-8f90-a1b2c3d4e5f6"}},"required":["listingId","idempotencyKey"]},"UserSummaryResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the user.","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"username":{"type":"string","description":"The handle used to link to the profile, /users/<username>.","example":"maker"},"displayName":{"type":"object","description":"Human-readable label. Falls back to the username client-side.","nullable":true,"example":"Maker"},"avatarUrl":{"type":"object","description":"The URL to the user's avatar.","nullable":true,"example":"https://users.helix-cdn.com/123e4567-e89b-12d3-a456-426614174000/avatar"}},"required":["id","username","displayName","avatarUrl"]},"BrandCreatorDto":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"object","nullable":true}},"required":["id","username","displayName"]},"CollectibleBrandResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Brand unique identifier"},"creator":{"description":"The creator of this brand","allOf":[{"$ref":"#/components/schemas/BrandCreatorDto"}]},"name":{"type":"string","description":"Brand name","example":"Luxury Motors"},"slug":{"type":"string","description":"URL-friendly unique identifier","example":"luxury-motors"},"description":{"type":"object","description":"Brand description","example":"Premium automotive collectibles","nullable":true},"logo":{"type":"string","description":"Dynamically generated logo URL","example":"https://cdn.example.com/brands/550e8400-e29b-41d4-a716-446655440000/logo"},"metadata":{"type":"object","description":"Arbitrary metadata","example":{"founded":"2023","category":"automotive"}},"createdAt":{"format":"date-time","type":"string","description":"When the brand was created"},"updatedAt":{"format":"date-time","type":"string","description":"When the brand was last updated"}},"required":["id","creator","name","slug","description","logo","metadata","createdAt","updatedAt"]},"NestedCollectibleDto":{"type":"object","properties":{"id":{"type":"string","description":"Collectible unique identifier"},"creatorId":{"type":"string","description":"Creator ID"},"creator":{"description":"The user who created this collectible. Null only when the creator row is genuinely missing — clients must render that as unknown, never synthesise a handle from creatorId.","nullable":true,"allOf":[{"$ref":"#/components/schemas/UserSummaryResponseDto"}]},"brandId":{"type":"object","description":"Brand ID (nullable)","nullable":true},"brand":{"description":"The brand associated with this collectible","nullable":true,"allOf":[{"$ref":"#/components/schemas/CollectibleBrandResponseDto"}]},"type":{"type":"string","enum":["Wearable","Placeable","Vehicle","Clothing","Accessory","Character","HomeItem","Property"],"description":"Type of collectible"},"name":{"type":"string","description":"Name of the collectible"},"slug":{"type":"string","description":"URL-friendly unique identifier"},"description":{"type":"string","description":"Description of the collectible"},"tags":{"description":"Tags for categorization","type":"array","items":{"type":"string"}},"supply":{"type":"number","description":"Total number of instances available"},"metadata":{"type":"object","description":"Custom metadata"},"isUniversal":{"type":"boolean","description":"Whether this collectible is universally compatible"},"isTransferable":{"type":"boolean","description":"Whether instances can be transferred by default"},"createdAt":{"format":"date-time","type":"string","description":"When this collectible was created"},"updatedAt":{"format":"date-time","type":"string","description":"When this collectible was last updated"},"thumbnail":{"type":"string","description":"Thumbnail CDN URL for this collectible","example":"https://cdn.example.com/collectibleId/thumbnail"},"threeDImage":{"type":"string","description":"3D image CDN URL for this collectible","example":"https://cdn.example.com/collectibleId/threedimage"},"previews":{"description":"Preview images for this collectible","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}}},"required":["id","creatorId","creator","brandId","brand","type","name","slug","description","tags","supply","metadata","isUniversal","isTransferable","createdAt","updatedAt","thumbnail","threeDImage"]},"InstancePreviewDto":{"type":"object","properties":{"key":{"type":"string","description":"Preview key/filename"},"url":{"type":"string","description":"CDN URL for the preview image"},"index":{"type":"number","description":"Display order index"}},"required":["key","url","index"]},"CollectibleInstanceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Instance unique identifier"},"serial":{"type":"number","description":"Serial number of this instance within the collectible supply"},"collectibleId":{"type":"string","description":"ID of the collectible this instance belongs to"},"collectible":{"description":"The collectible this instance belongs to","allOf":[{"$ref":"#/components/schemas/NestedCollectibleDto"}]},"ownerId":{"type":"object","description":"ID of the current owner (null if not yet claimed)","nullable":true},"owner":{"description":"The user who currently owns this instance. Null when the instance is unowned — clients must render that as unknown, never synthesise a handle from ownerId.","nullable":true,"allOf":[{"$ref":"#/components/schemas/UserSummaryResponseDto"}]},"isTransferable":{"type":"boolean","description":"Whether this specific instance can be transferred"},"location":{"type":"object","description":"Location of this instance (user, server, etc.)","nullable":true},"usage":{"type":"object","description":"Generic usage metrics"},"traits":{"type":"object","description":"Instance-specific traits"},"isLocked":{"type":"boolean","description":"Whether this instance is locked (currently listed on marketplace)"},"lockedByListingId":{"type":"object","description":"ID of the listing that locked this instance (null if not locked)","nullable":true},"lockedAt":{"type":"object","description":"When this instance was locked (null if not locked)","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"When this instance was created"},"updatedAt":{"format":"date-time","type":"string","description":"When this instance was last updated"},"thumbnail":{"type":"string","description":"Thumbnail CDN URL for this instance","example":"https://cdn.example.com/collectibleId/instanceId/thumbnail"},"threeDImage":{"type":"string","description":"3D image CDN URL for this instance","example":"https://cdn.example.com/collectibleId/instanceId/threedimage"},"previews":{"description":"Preview images for this instance","type":"array","items":{"$ref":"#/components/schemas/InstancePreviewDto"}},"activeListing":{"type":"object","description":"Active listing for this instance (if any)","nullable":true},"highestOfferPrice":{"type":"number","description":"Highest offer price for the active listing (if any)","nullable":true,"example":100.5}},"required":["id","serial","collectibleId","ownerId","owner","isTransferable","location","usage","traits","isLocked","lockedByListingId","lockedAt","createdAt","updatedAt","thumbnail","threeDImage","activeListing","highestOfferPrice"]},"CollectibleListingResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Listing unique identifier"},"collectibleInstanceId":{"type":"string","description":"ID of the collectible instance being listed"},"universalItemId":{"type":"object","description":"Canonical universal item ID for the listed collectible (null for legacy standalone collectibles)","nullable":true},"collectibleInstance":{"description":"The collectible instance being listed","allOf":[{"$ref":"#/components/schemas/CollectibleInstanceResponseDto"}]},"sellerId":{"type":"string","description":"ID of the seller"},"seller":{"description":"The seller user object","allOf":[{"$ref":"#/components/schemas/UserResponseDto"}]},"listingType":{"type":"string","description":"Type of listing","enum":["FIXED_PRICE","OFFER_BASED"]},"lixPrice":{"type":"number","description":"Price in LIX. For FIXED_PRICE listings: the fixed price. For OFFER_BASED listings: instant buy price (if allowInstantBuy is true, null otherwise)","nullable":true},"startingLixPrice":{"type":"number","description":"Starting price for offers in LIX (null for fixed-price listings)","nullable":true},"allowInstantBuy":{"type":"boolean","description":"Whether instant buy is allowed for this offer-based listing (requires lixPrice to be set)"},"status":{"type":"string","description":"Current status of the listing","enum":["ACTIVE","SOLD","CANCELLED"]},"createdAt":{"format":"date-time","type":"string","description":"When this listing was created"},"updatedAt":{"format":"date-time","type":"string","description":"When this listing was last updated"},"soldAt":{"type":"object","description":"When this listing was sold (null if not sold)","nullable":true}},"required":["id","collectibleInstanceId","universalItemId","sellerId","listingType","lixPrice","startingLixPrice","allowInstantBuy","status","createdAt","updatedAt","soldAt"]},"PlaceOfferRequestDto":{"type":"object","properties":{"listingId":{"type":"string","description":"ID of the listing to make an offer on","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"offerAmount":{"type":"number","description":"Offer amount in LIX","example":75.5,"minimum":0.0001}},"required":["listingId","offerAmount"]},"CollectibleOfferResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the offer","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"listingId":{"type":"string","description":"ID of the listing this offer is for","example":"b2c3d4e5-f6a7-8901-bcde-f12345678901"},"buyerId":{"type":"string","description":"ID of the buyer making the offer","example":"c3d4e5f6-a7b8-9012-cdef-123456789012"},"offerLixAmount":{"type":"string","description":"Offer amount in LIX","example":"75.5000"},"escrowTransactionId":{"type":"string","description":"Transaction ID for the escrowed funds","example":"d4e5f6a7-b8c9-0123-def1-234567890123"},"status":{"type":"string","description":"Status of the offer","enum":["PENDING","ACCEPTED","REJECTED","RELEASED","WITHDRAWN","EXPIRED"],"example":"PENDING"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the offer was created","example":"2025-10-27T12:00:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the offer was last updated","example":"2025-10-27T12:00:00.000Z"},"resolvedAt":{"type":"object","description":"Timestamp when the offer was resolved (accepted/rejected/withdrawn/expired)","example":"2025-10-27T13:00:00.000Z","nullable":true},"expiresAt":{"format":"date-time","type":"string","description":"Timestamp when a PENDING offer auto-expires (7 days after creation); the escrow sweeper releases the buyer's LIX at this point.","example":"2025-11-03T12:00:00.000Z"}},"required":["id","listingId","buyerId","offerLixAmount","escrowTransactionId","status","createdAt","updatedAt","resolvedAt","expiresAt"]},"PublicCollectibleOfferResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the offer","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"listingId":{"type":"string","description":"ID of the listing this offer is for","example":"b2c3d4e5-f6a7-8901-bcde-f12345678901"},"buyerId":{"type":"string","description":"ID of the buyer making the offer","example":"c3d4e5f6-a7b8-9012-cdef-123456789012"},"offerLixAmount":{"type":"number","description":"Offer amount in LIX","example":75.5},"status":{"type":"string","description":"Status of the offer","enum":["PENDING","ACCEPTED","REJECTED","RELEASED","WITHDRAWN","EXPIRED"],"example":"PENDING"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the offer was created","example":"2025-10-27T12:00:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the offer was last updated","example":"2025-10-27T12:00:00.000Z"},"resolvedAt":{"type":"object","description":"Timestamp when the offer was resolved (accepted/rejected/withdrawn)","example":"2025-10-27T13:00:00.000Z","nullable":true}},"required":["id","listingId","buyerId","offerLixAmount","status","createdAt","updatedAt","resolvedAt"]},"CancelOfferRequestDto":{"type":"object","properties":{"offerId":{"type":"string","description":"ID of the offer to cancel","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}},"required":["offerId"]},"RejectOfferRequestDto":{"type":"object","properties":{"offerId":{"type":"string","description":"The UUID of the offer to reject","example":"123e4567-e89b-12d3-a456-426614174000"}},"required":["offerId"]},"AcceptOfferRequestDto":{"type":"object","properties":{"offerId":{"type":"string","description":"The UUID of the offer to accept","example":"123e4567-e89b-12d3-a456-426614174000"}},"required":["offerId"]},"VerificationClaimFlagsDto":{"type":"object","properties":{"phoneVerified":{"type":"boolean"},"identityVerified":{"type":"boolean"},"adultVerified":{"type":"boolean"}},"required":["phoneVerified","identityVerified","adultVerified"]},"VerificationVisibilityResponseDto":{"type":"object","properties":{"eligibility":{"description":"Server-authoritative eligibility. This contains no phone, provider, date of birth, age band, or minor status.","allOf":[{"$ref":"#/components/schemas/VerificationClaimFlagsDto"}]},"visibility":{"description":"The account owner public-profile opt-ins. Defaults to false.","allOf":[{"$ref":"#/components/schemas/VerificationClaimFlagsDto"}]}},"required":["eligibility","visibility"]},"UpdateVerificationVisibilityRequestDto":{"type":"object","properties":{"phoneVerified":{"type":"boolean","description":"Show the Level 1 phone-verified claim on the public profile."},"identityVerified":{"type":"boolean","description":"Show the Level 2 identity-verified claim on the public profile."},"adultVerified":{"type":"boolean","description":"Show the adult-verified claim on the public profile. Requires an authoritative adult verification and Level 2 identity verification."}}},"CreatePendingPurchaseDto":{"type":"object","properties":{"amount":{"type":"number","description":"Amount in cents to charge","example":1000,"minimum":1},"currency":{"type":"string","description":"Currency code","example":"usd","enum":["usd"]},"payment_method_id":{"type":"string","description":"Optional Stripe payment method ID to use for one-click payment","example":"pm_1Pvq5h2eZvKYlo2C0abc1234"},"success_callback_url":{"type":"string","description":"Optional callback URL to redirect after successful payment","example":"https://example.com/payment/success"},"cancel_callback_url":{"type":"string","description":"Optional callback URL to redirect after cancelled payment","example":"https://example.com/payment/cancel"}},"required":["amount","currency"]},"CreateEmbeddedSessionDto":{"type":"object","properties":{"amount":{"type":"number","description":"Amount in cents to charge","example":1000,"minimum":1},"currency":{"type":"string","description":"Currency code","example":"usd","enum":["usd"]},"payment_method_id":{"type":"string","description":"Optional Stripe payment method ID to use for one-click payment","example":"pm_1Pvq5h2eZvKYlo2C0abc1234"},"success_callback_url":{"type":"string","description":"Optional callback URL to redirect after successful payment","example":"https://example.com/payment/success"},"cancel_callback_url":{"type":"string","description":"Optional callback URL to redirect after cancelled payment","example":"https://example.com/payment/cancel"}},"required":["amount","currency"]},"ConfirmPaymentDto":{"type":"object","properties":{"amount":{"type":"number","description":"Amount in cents to charge","example":1000,"minimum":1},"currency":{"type":"string","description":"Currency code","example":"usd","enum":["usd"]},"payment_method_id":{"type":"string","description":"Stripe PaymentMethod ID created on frontend","example":"pm_1Pvq5h2eZvKYlo2C0abc1234"},"save_payment_method":{"type":"boolean","description":"Whether to save the payment method for future use","example":true},"success_callback_url":{"type":"string","description":"Optional callback URL to redirect after successful payment","example":"https://example.com/payment/success"},"cancel_callback_url":{"type":"string","description":"Optional callback URL to redirect after cancelled payment","example":"https://example.com/payment/cancel"}},"required":["amount","currency","payment_method_id"]},"PurchaseLIXBundleDto":{"type":"object","properties":{"bundleId":{"type":"string","description":"The UUID of the LIX bundle to purchase","example":"123e4567-e89b-12d3-a456-426614174000"}},"required":["bundleId"]},"LixBundleResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the bundle","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Name of the LIX bundle","example":"Starter Pack"},"description":{"type":"string","description":"Description of the bundle","example":"Perfect for new users getting started with LIX"},"lixAmount":{"type":"number","description":"Amount of LIX included in the bundle","example":1000},"fixedPrice":{"type":"object","description":"Fixed price in cents (USD)","example":999,"nullable":true},"discountPercentage":{"type":"object","description":"Discount percentage (0-100)","example":20,"nullable":true},"isActive":{"type":"boolean","description":"Whether the bundle is active and available for purchase","example":true},"displayOrder":{"type":"number","description":"Display order for frontend sorting","example":0},"metadata":{"type":"object","description":"Additional metadata for the bundle","example":{"featured":true}},"createdAt":{"format":"date-time","type":"string","description":"Bundle creation timestamp","example":"2024-01-15T10:30:00Z"},"updatedAt":{"format":"date-time","type":"string","description":"Bundle last update timestamp","example":"2024-01-15T15:45:00Z"},"deletedAt":{"type":"object","description":"Soft deletion timestamp","example":null,"nullable":true}},"required":["id","name","description","lixAmount","isActive","displayOrder","metadata","createdAt","updatedAt"]},"CreateLixBundleDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the LIX bundle","example":"Starter Pack","minLength":1,"maxLength":100},"description":{"type":"string","description":"Detailed description of the bundle","example":"Perfect for new users getting started with LIX"},"lixAmount":{"type":"number","description":"Amount of LIX included in the bundle","example":1000},"fixedPrice":{"type":"number","description":"Fixed price in cents (USD). If set, overrides discount percentage calculation.","example":999,"minimum":1},"discountPercentage":{"type":"number","description":"Discount percentage (0-100). Used to calculate price if fixedPrice is not set.","example":20,"minimum":0,"maximum":100},"isActive":{"type":"boolean","description":"Whether the bundle is active and available for purchase","example":true,"default":true},"displayOrder":{"type":"number","description":"Display order for frontend sorting (lower values first)","example":0,"default":0},"metadata":{"type":"object","description":"Additional metadata for the bundle (promotional info, etc.)","example":{"featured":true,"badge":"BEST_VALUE"}}},"required":["name","description","lixAmount"]},"UpdateLixBundleDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the LIX bundle","example":"Starter Pack","minLength":1,"maxLength":100},"description":{"type":"string","description":"Detailed description of the bundle","example":"Perfect for new users getting started with LIX"},"lixAmount":{"type":"number","description":"Amount of LIX included in the bundle","example":1000},"fixedPrice":{"type":"number","description":"Fixed price in cents (USD). If set, overrides discount percentage calculation.","example":999,"minimum":1},"discountPercentage":{"type":"object","description":"Discount percentage (0-100). Used to calculate price if fixedPrice is not set.","example":20,"minimum":0,"maximum":100},"isActive":{"type":"boolean","description":"Whether the bundle is active and available for purchase","example":true},"displayOrder":{"type":"number","description":"Display order for frontend sorting (lower values first)","example":0},"metadata":{"type":"object","description":"Additional metadata for the bundle (promotional info, etc.)","example":{"featured":true,"badge":"BEST_VALUE"}}}},"AmountBreakdownDto":{"type":"object","properties":{"withdrawable":{"type":"number","description":"Withdrawable amount","example":50.25},"non_withdrawable":{"type":"number","description":"Non-withdrawable amount","example":25.75}},"required":["withdrawable","non_withdrawable"]},"TransactionInWorldPurchaseWorldDto":{"type":"object","properties":{"id":{"type":"object","description":"World id.","nullable":true},"slug":{"type":"object","description":"World slug.","nullable":true},"title":{"type":"string","description":"World title."},"detailPath":{"type":"object","description":"Stable frontend target for the world detail view.","nullable":true}},"required":["id","slug","title","detailPath"]},"TransactionInWorldPurchaseProductDto":{"type":"object","properties":{"id":{"type":"object","description":"World product id, when registered.","nullable":true},"key":{"type":"string","description":"Stable product reference key."},"title":{"type":"string","description":"Product title."},"description":{"type":"object","description":"Product description.","nullable":true},"type":{"type":"object","description":"World product type.","nullable":true},"itemId":{"type":"object","description":"Granted/target item id.","nullable":true},"priceLix":{"type":"object","description":"Price in LIX.","nullable":true}},"required":["id","key","title","description","type","itemId","priceLix"]},"TransactionInWorldPurchaseSummaryDto":{"type":"object","properties":{"category":{"type":"string","description":"Wallet display category."},"refType":{"type":"string","description":"Purchase reference type."},"purchaseId":{"type":"object","description":"In-world purchase ledger id.","nullable":true},"status":{"type":"object","description":"In-world purchase ledger status.","nullable":true},"world":{"$ref":"#/components/schemas/TransactionInWorldPurchaseWorldDto"},"product":{"$ref":"#/components/schemas/TransactionInWorldPurchaseProductDto"}},"required":["category","refType","purchaseId","status","world","product"]},"TransactionCollectionResponseDto":{"type":"object","properties":{"transaction_id":{"type":"string","description":"Unique transaction identifier","example":"txn_123456789"},"idempotency_key":{"type":"string","description":"Idempotency key for the transaction","example":"idem_123456789"},"source_wallet_id":{"type":"string","description":"Source wallet ID","example":"wallet_123"},"destination_wallet_id":{"type":"string","description":"Destination wallet ID","example":"wallet_456"},"amount":{"type":"number","description":"Transaction amount","example":76},"amount_breakdown":{"description":"Amount breakdown between withdrawable and non-withdrawable","allOf":[{"$ref":"#/components/schemas/AmountBreakdownDto"}]},"type":{"type":"string","description":"Transaction type","example":"purchase"},"status":{"type":"string","description":"Real settlement state, straight from the ledger — never assume success. `locked` is an OPEN escrow: a live generation holds its estimated ceiling here for up to 24h and the unspent remainder comes back afterwards, so a locked row is money reserved, not money spent. `reverted` means the hold was returned in full.","example":"completed","enum":["pending","locked","completed","reverted","failed","expired"]},"metadata":{"type":"object","description":"Additional metadata for the transaction"},"in_world_purchase":{"description":"In-world purchase display metadata when this wallet transaction came from a world purchase.","nullable":true,"allOf":[{"$ref":"#/components/schemas/TransactionInWorldPurchaseSummaryDto"}]},"processed_at":{"type":"string","description":"When the transaction was processed","example":"2023-12-01T10:30:00Z"},"created_at":{"type":"string","description":"When the transaction was created","example":"2023-12-01T10:25:00Z"},"maturity_date":{"type":"string","description":"The date when funds from this transaction will become withdrawable","example":"2026-02-25T09:59:03.192Z"},"reason":{"type":"object","description":"Transaction reason extracted from metadata (e.g. collectibles_offer_lock, collectibles_offer_accepted)","nullable":true}},"required":["transaction_id","idempotency_key","amount","amount_breakdown","type","status","created_at"]},"TransactionCollectibleTradeSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Trade ID"},"collectibleId":{"type":"string","description":"Collectible ID"},"collectibleInstanceId":{"type":"string","description":"Collectible instance ID"},"listingId":{"type":"string","description":"Listing ID"},"sellerId":{"type":"string","description":"Seller user ID"},"buyerId":{"type":"string","description":"Buyer user ID"},"grossLixAmount":{"type":"string","description":"Gross LIX amount"},"tradeType":{"type":"string","description":"Trade type (INSTANT_BUY or OFFER_ACCEPTED)"},"completedAt":{"format":"date-time","type":"string","description":"Trade completion timestamp"},"collectibleName":{"type":"object","description":"Collectible name","nullable":true},"collectibleBrand":{"type":"object","description":"Collectible brand name","nullable":true},"collectibleThumbnail":{"type":"object","description":"Collectible thumbnail URL","nullable":true},"collectibleImage":{"type":"object","description":"Collectible image URL (3D image when available)","nullable":true},"collectibleInstanceSerial":{"type":"object","description":"Collectible instance serial number","nullable":true},"collectibleInstanceThumbnail":{"type":"object","description":"Collectible instance thumbnail URL","nullable":true},"collectibleInstanceImage":{"type":"object","description":"Collectible instance image URL (3D image when available)","nullable":true}},"required":["id","collectibleId","collectibleInstanceId","listingId","sellerId","buyerId","grossLixAmount","tradeType","completedAt"]},"TransactionCollectibleOfferSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Offer ID"},"listingId":{"type":"string","description":"Listing ID this offer belongs to"},"buyerId":{"type":"string","description":"Buyer ID who created the offer"},"offerLixAmount":{"type":"string","description":"Offered amount in LIX"},"escrowTransactionId":{"type":"string","description":"Escrow transaction ID used for this offer"},"status":{"type":"string","description":"Current offer status","enum":["PENDING","ACCEPTED","REJECTED","RELEASED","WITHDRAWN","EXPIRED"]},"createdAt":{"format":"date-time","type":"string","description":"Offer creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Offer update timestamp"},"resolvedAt":{"type":"object","description":"Offer resolution timestamp (accepted/rejected/withdrawn)","nullable":true},"collectibleInstanceId":{"type":"object","description":"Collectible instance ID","nullable":true},"collectibleName":{"type":"object","description":"Collectible name","nullable":true},"collectibleBrand":{"type":"object","description":"Collectible brand name","nullable":true},"collectibleThumbnail":{"type":"object","description":"Collectible thumbnail URL","nullable":true},"collectibleImage":{"type":"object","description":"Collectible image URL (3D image when available)","nullable":true},"collectibleInstanceSerial":{"type":"object","description":"Collectible instance serial number","nullable":true},"collectibleInstanceThumbnail":{"type":"object","description":"Collectible instance thumbnail URL","nullable":true},"collectibleInstanceImage":{"type":"object","description":"Collectible instance image URL (3D image when available)","nullable":true}},"required":["id","listingId","buyerId","offerLixAmount","escrowTransactionId","status","createdAt","updatedAt"]},"TransactionDetailedResponseDto":{"type":"object","properties":{"transaction_id":{"type":"string","description":"Unique transaction identifier","example":"txn_123456789"},"idempotency_key":{"type":"string","description":"Idempotency key for the transaction","example":"idem_123456789"},"source_wallet_id":{"type":"string","description":"Source wallet ID","example":"wallet_123"},"destination_wallet_id":{"type":"string","description":"Destination wallet ID","example":"wallet_456"},"amount":{"type":"number","description":"Transaction amount","example":76},"amount_breakdown":{"description":"Amount breakdown between withdrawable and non-withdrawable","allOf":[{"$ref":"#/components/schemas/AmountBreakdownDto"}]},"type":{"type":"string","description":"Transaction type","example":"purchase"},"status":{"type":"string","description":"Real settlement state, straight from the ledger — never assume success. `locked` is an OPEN escrow: a live generation holds its estimated ceiling here for up to 24h and the unspent remainder comes back afterwards, so a locked row is money reserved, not money spent. `reverted` means the hold was returned in full.","example":"completed","enum":["pending","locked","completed","reverted","failed","expired"]},"metadata":{"type":"object","description":"Additional metadata for the transaction"},"in_world_purchase":{"description":"In-world purchase display metadata when this wallet transaction came from a world purchase.","nullable":true,"allOf":[{"$ref":"#/components/schemas/TransactionInWorldPurchaseSummaryDto"}]},"processed_at":{"type":"string","description":"When the transaction was processed","example":"2023-12-01T10:30:00Z"},"created_at":{"type":"string","description":"When the transaction was created","example":"2023-12-01T10:25:00Z"},"maturity_date":{"type":"string","description":"The date when funds from this transaction will become withdrawable","example":"2026-02-25T09:59:03.192Z"},"reason":{"type":"object","description":"Transaction reason extracted from metadata (e.g. collectibles_offer_lock, collectibles_offer_accepted)","nullable":true},"order":{"description":"Related order details (if this transaction is tied to an order)","nullable":true,"allOf":[{"$ref":"#/components/schemas/OrderResponseDto"}]},"collectible_trade":{"description":"Related collectible trade details (if this transaction is tied to a collectible trade)","nullable":true,"allOf":[{"$ref":"#/components/schemas/TransactionCollectibleTradeSummaryDto"}]},"collectible_offer":{"description":"Related collectible offer details (if this transaction is tied to a collectible offer)","nullable":true,"allOf":[{"$ref":"#/components/schemas/TransactionCollectibleOfferSummaryDto"}]}},"required":["transaction_id","idempotency_key","amount","amount_breakdown","type","status","created_at"]},"PendingMaturityDto":{"type":"object","properties":{"maturity_id":{"type":"string","description":"Unique maturity record identifier","example":"4b66e9a0-c4cf-4d12-b099-4063b90ba751"},"amount":{"type":"number","description":"Amount that will become withdrawable when matured","example":100.5},"maturity_date":{"type":"string","description":"Date when the funds will become withdrawable","example":"2026-02-25T09:59:03.192Z"},"days_remaining":{"type":"number","description":"Number of days remaining until maturity","example":90},"source_transaction_id":{"type":"string","description":"ID of the source transaction that created this maturity","example":"89a84fd4-013e-488f-9177-43238fb6d1dc"},"created_at":{"type":"string","description":"When the maturity record was created","example":"2025-11-27T07:00:43.462Z"}},"required":["maturity_id","amount","maturity_date","days_remaining","source_transaction_id","created_at"]},"CreateWorldItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"ID of the world item"},"slug":{"type":"string","description":"Slug of the world item"},"name":{"type":"string","description":"Name of the world item"},"description":{"type":"string","description":"Description of the world item"},"thumbnail":{"type":"string","description":"Thumbnail URL"},"thumbnailUploadUrl":{"type":"string","description":"Presigned URL for uploading the thumbnail"},"priceLix":{"type":"number","description":"Price in Lix","example":99.99},"available":{"type":"boolean","description":"Whether the item is available"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Update timestamp"}},"required":["id","slug","name","description","thumbnail","thumbnailUploadUrl","priceLix","available","createdAt","updatedAt"]},"CreateWorldItemRequestDto":{"type":"object","properties":{"slug":{"type":"string","description":"The unique slug of the world item.","example":"diamond-sword"},"name":{"type":"string","description":"The name of the world item.","example":"Diamond Sword"},"description":{"type":"string","description":"The description of the world item.","example":"A powerful sword made of diamond."},"priceLix":{"type":"number","description":"The price in Lix currency for the world item.","example":99.99},"available":{"type":"boolean","description":"Whether the world item is available for purchase.","example":true,"default":true}},"required":["slug","name","description","priceLix"]},"UpdateWorldItemRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the world item.","example":"Diamond Sword"},"description":{"type":"string","description":"The description of the world item.","example":"A powerful sword made of diamond."},"priceLix":{"type":"number","description":"The price in Lix currency for the world item.","example":99.99},"available":{"type":"boolean","description":"Whether the world item is available for purchase.","example":true}}},"DeleteWorldItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"ID of the deleted world item"},"message":{"type":"string","description":"Success message"}},"required":["id","message"]},"DeleteWorldItemsResponseDto":{"type":"object","properties":{"deletedIds":{"description":"Array of successfully deleted world item IDs","type":"array","items":{"type":"string"}},"failedIds":{"description":"Array of world item IDs that failed to delete","type":"array","items":{"type":"string"}},"deletedCount":{"type":"number","description":"Number of successfully deleted world items"},"message":{"type":"string","description":"Success message"}},"required":["deletedIds","failedIds","deletedCount","message"]},"DeleteWorldItemsRequestDto":{"type":"object","properties":{"worldItemIds":{"description":"Array of world item IDs to delete","example":["550e8400-e29b-41d4-a716-446655440000","550e8400-e29b-41d4-a716-446655440001"],"minItems":1,"maxItems":100,"type":"array","items":{"type":"string"}}},"required":["worldItemIds"]},"PublicVerificationClaimsDto":{"type":"object","properties":{"phoneVerified":{"type":"boolean"},"identityVerified":{"type":"boolean"},"adultVerified":{"type":"boolean"}},"required":["phoneVerified","identityVerified","adultVerified"]},"PublicUserProfileResponseDto":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"object","nullable":true},"avatarUrl":{"type":"object","nullable":true},"country":{"type":"object","nullable":true},"verificationClaims":{"description":"Opt-in verification claims only. No phone, provider, DOB, age band, or minor status is public.","allOf":[{"$ref":"#/components/schemas/PublicVerificationClaimsDto"}]}},"required":["id","username","displayName","avatarUrl","country","verificationClaims"]},"PublicPackageVersionDependencyDto":{"type":"object","properties":{"id":{"type":"string","description":"Dependency package version ID"},"packageId":{"type":"string","description":"Dependency package ID"},"isPrivate":{"type":"boolean","description":"Whether the dependency package is private"},"name":{"type":"object","description":"Name of the dependency package or placeholder when private","nullable":true},"slug":{"type":"object","description":"Slug of the dependency package (null when private)","nullable":true},"type":{"type":"object","description":"Type of the dependency package (null when private)","nullable":true}},"required":["id","packageId","isPrivate","name","slug","type"]},"PublicPackageVersionPartialDto":{"type":"object","properties":{"id":{"type":"string"},"packageId":{"type":"string"},"revision":{"type":"number"},"config":{"type":"object"},"clientSize":{"type":"number"},"serverSize":{"type":"number"},"editorSize":{"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"publishedAt":{"format":"date-time","type":"string","nullable":true},"releaseNotes":{"type":"object","description":"Release notes describing changes for this version.","nullable":true},"dependencyIds":{"type":"array","items":{"type":"string"}},"dependentIds":{"type":"array","items":{"type":"string"}},"dependencies":{"type":"array","items":{"$ref":"#/components/schemas/PublicPackageVersionDependencyDto"}}},"required":["id","packageId","revision","config","clientSize","serverSize","editorSize","createdAt","updatedAt","publishedAt","releaseNotes","dependencyIds","dependentIds","dependencies"]},"PublicUserResponseDto":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"object","nullable":true},"avatarUrl":{"type":"object","nullable":true},"country":{"type":"object","nullable":true}},"required":["id","username","displayName","avatarUrl","country"]},"PublicPackageCollectionResponseDto":{"type":"object","properties":{"id":{"type":"string"},"creatorId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["World","Map","QRE","Vehicle","Character","Character Preset","Weapon","Wearable","Animation","Structure","Interior","Tool","Effect","Sound","Script","Addon","EDL","Other"]},"contentRating":{"type":"string","enum":["Everyone","Teen","Mature","Adult"]},"previews":{"type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"tags":{"type":"array","items":{"type":"string"}},"downloads":{"type":"number"},"currentRating":{"type":"number"},"totalRatings":{"type":"number"},"isPrivate":{"type":"boolean"},"thumbsUpPercentage":{"type":"string"},"totalReviews":{"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"publishedAt":{"format":"date-time","type":"string","nullable":true},"lastReleaseAt":{"format":"date-time","type":"string","nullable":true},"latestVersion":{"$ref":"#/components/schemas/PublicPackageVersionPartialDto"},"creator":{"$ref":"#/components/schemas/PublicUserResponseDto"}},"required":["id","creatorId","name","slug","description","type","contentRating","previews","tags","downloads","currentRating","totalRatings","isPrivate","thumbsUpPercentage","totalReviews","createdAt","updatedAt","publishedAt","lastReleaseAt","latestVersion","creator"]},"PublicPackageResponseDto":{"type":"object","properties":{"id":{"type":"string"},"creatorId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["World","Map","QRE","Vehicle","Character","Character Preset","Weapon","Wearable","Animation","Structure","Interior","Tool","Effect","Sound","Script","Addon","EDL","Other"]},"contentRating":{"type":"string","enum":["Everyone","Teen","Mature","Adult"]},"previews":{"type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"tags":{"type":"array","items":{"type":"string"}},"downloads":{"type":"number"},"currentRating":{"type":"number"},"totalRatings":{"type":"number"},"isPrivate":{"type":"boolean"},"thumbsUpPercentage":{"type":"string"},"totalReviews":{"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"publishedAt":{"format":"date-time","type":"string","nullable":true},"lastReleaseAt":{"format":"date-time","type":"string","nullable":true},"latestVersion":{"$ref":"#/components/schemas/PublicPackageVersionPartialDto"},"versions":{"type":"array","items":{"$ref":"#/components/schemas/PublicPackageVersionPartialDto"}},"creator":{"$ref":"#/components/schemas/PublicUserResponseDto"}},"required":["id","creatorId","name","slug","description","type","contentRating","previews","tags","downloads","currentRating","totalRatings","isPrivate","thumbsUpPercentage","totalReviews","createdAt","updatedAt","publishedAt","lastReleaseAt","latestVersion","versions","creator"]},"PublicPackageVersionWithDetailsDto":{"type":"object","properties":{"id":{"type":"string"},"packageId":{"type":"string"},"revision":{"type":"number"},"config":{"type":"object"},"clientSize":{"type":"number"},"serverSize":{"type":"number"},"editorSize":{"type":"number"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"publishedAt":{"format":"date-time","type":"string","nullable":true},"releaseNotes":{"type":"object","description":"Release notes describing changes for this version.","nullable":true},"dependencyIds":{"type":"array","items":{"type":"string"}},"dependentIds":{"type":"array","items":{"type":"string"}},"dependencies":{"type":"array","items":{"$ref":"#/components/schemas/PublicPackageVersionDependencyDto"}},"package":{"description":"The package details.","allOf":[{"$ref":"#/components/schemas/PublicPackageResponseDto"}]}},"required":["id","packageId","revision","config","clientSize","serverSize","editorSize","createdAt","updatedAt","publishedAt","releaseNotes","dependencyIds","dependentIds","dependencies","package"]},"PublicServerResponseDto":{"type":"object","properties":{"id":{"type":"string"},"ownerId":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"contentRating":{"type":"string"},"gameMode":{"type":"string"},"hostingType":{"type":"string"},"gameVersion":{"type":"string"},"currentPlayers":{"type":"number"},"maxPlayers":{"type":"number"},"status":{"type":"string"},"visits":{"type":"number"},"publishedAt":{"format":"date-time","type":"string","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"owner":{"$ref":"#/components/schemas/PublicUserResponseDto"},"map":{"$ref":"#/components/schemas/PublicPackageVersionWithDetailsDto"},"packageVersions":{"type":"array","items":{"$ref":"#/components/schemas/PublicPackageVersionPartialDto"}}},"required":["id","ownerId","slug","name","description","tags","contentRating","gameMode","hostingType","gameVersion","currentPlayers","maxPlayers","status","visits","publishedAt","createdAt","updatedAt","owner","map","packageVersions"]},"PublicCollectibleCompatiblePackageDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}},"required":["id","name","slug"]},"PublicCollectibleResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Collectible unique identifier"},"creator":{"description":"The creator/owner of this collectible","allOf":[{"$ref":"#/components/schemas/PublicUserResponseDto"}]},"creatorId":{"type":"string","description":"Creator ID"},"type":{"type":"string","enum":["Wearable","Placeable","Vehicle","Clothing","Accessory","Character","HomeItem","Property"],"description":"Type of collectible"},"name":{"type":"string","description":"Name of the collectible"},"slug":{"type":"string","description":"URL-friendly unique identifier"},"description":{"type":"string","description":"Description of the collectible"},"tags":{"description":"Tags for categorization","type":"array","items":{"type":"string"}},"supply":{"type":"number","description":"Total number of instances available"},"metadata":{"type":"object","description":"Custom metadata"},"thumbnail":{"type":"object","description":"Thumbnail image URL or key","nullable":true},"threeDImage":{"type":"object","description":"3D image URL","nullable":true},"previews":{"description":"The previews of the collectible","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"isUniversal":{"type":"boolean","description":"Whether this collectible is universally compatible"},"compatiblePackages":{"description":"Compatible packages (if not universal)","type":"array","items":{"$ref":"#/components/schemas/PublicCollectibleCompatiblePackageDto"}},"isTransferable":{"type":"boolean","description":"Whether instances can be transferred by default"},"avgSalePrice":{"type":"number","description":"Average sale price across all trades","example":150.5},"allTimeHighPrice":{"type":"number","description":"All-time highest sale price","example":500},"totalVolumeTraded":{"type":"number","description":"Total volume traded (sum of all sales)","example":3500},"totalSalesCount":{"type":"number","description":"Total number of sales/trades","example":25},"lastSalePrice":{"type":"object","description":"Most recent sale price","example":175,"nullable":true},"lastSaleAt":{"type":"object","description":"Timestamp of the most recent sale","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"When this collectible was created"},"updatedAt":{"format":"date-time","type":"string","description":"When this collectible was last updated"}},"required":["id","creator","creatorId","type","name","slug","description","tags","supply","metadata","thumbnail","threeDImage","previews","isUniversal","compatiblePackages","isTransferable","avgSalePrice","allTimeHighPrice","totalVolumeTraded","totalSalesCount","lastSalePrice","lastSaleAt","createdAt","updatedAt"]},"PublicNestedCollectibleDto":{"type":"object","properties":{"id":{"type":"string","description":"Collectible unique identifier"},"creatorId":{"type":"string","description":"Creator ID"},"type":{"type":"string","enum":["Wearable","Placeable","Vehicle","Clothing","Accessory","Character","HomeItem","Property"],"description":"Type of collectible"},"name":{"type":"string","description":"Name of the collectible"},"slug":{"type":"string","description":"URL-friendly unique identifier"},"description":{"type":"string","description":"Description of the collectible"},"tags":{"description":"Tags for categorization","type":"array","items":{"type":"string"}},"supply":{"type":"number","description":"Total number of instances available"},"metadata":{"type":"object","description":"Custom metadata"},"isUniversal":{"type":"boolean","description":"Whether this collectible is universally compatible"},"isTransferable":{"type":"boolean","description":"Whether instances can be transferred by default"},"createdAt":{"format":"date-time","type":"string","description":"When this collectible was created"},"updatedAt":{"format":"date-time","type":"string","description":"When this collectible was last updated"},"thumbnail":{"type":"string","description":"Thumbnail CDN URL for this collectible","example":"https://cdn.example.com/collectibleId/thumbnail"},"threeDImage":{"type":"string","description":"3D image CDN URL for this collectible","example":"https://cdn.example.com/collectibleId/threedimage"},"previews":{"description":"Preview images for this collectible","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}}},"required":["id","creatorId","type","name","slug","description","tags","supply","metadata","isUniversal","isTransferable","createdAt","updatedAt","thumbnail","threeDImage"]},"PublicInstancePreviewDto":{"type":"object","properties":{"key":{"type":"string","description":"Preview key/filename"},"url":{"type":"string","description":"CDN URL for the preview image"},"index":{"type":"number","description":"Display order index"}},"required":["key","url","index"]},"PublicCollectibleInstanceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Instance unique identifier"},"serial":{"type":"number","description":"Serial number of this instance within the collectible supply"},"collectibleId":{"type":"string","description":"ID of the collectible this instance belongs to"},"collectible":{"description":"The collectible this instance belongs to","allOf":[{"$ref":"#/components/schemas/PublicNestedCollectibleDto"}]},"ownerId":{"type":"object","description":"ID of the current owner (null if not yet claimed)","nullable":true},"isTransferable":{"type":"boolean","description":"Whether this specific instance can be transferred"},"location":{"type":"object","description":"Location of this instance (user, server, etc.)","nullable":true},"usage":{"type":"object","description":"Generic usage metrics"},"traits":{"type":"object","description":"Instance-specific traits"},"isLocked":{"type":"boolean","description":"Whether this instance is locked (currently listed on marketplace)"},"lockedByListingId":{"type":"object","description":"ID of the listing that locked this instance (null if not locked)","nullable":true},"lockedAt":{"type":"object","description":"When this instance was locked (null if not locked)","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"When this instance was created"},"updatedAt":{"format":"date-time","type":"string","description":"When this instance was last updated"},"thumbnail":{"type":"string","description":"Thumbnail CDN URL for this instance","example":"https://cdn.example.com/collectibleId/instanceId/thumbnail"},"threeDImage":{"type":"string","description":"3D image CDN URL for this instance","example":"https://cdn.example.com/collectibleId/instanceId/threedimage"},"previews":{"description":"Preview images for this instance","type":"array","items":{"$ref":"#/components/schemas/PublicInstancePreviewDto"}}},"required":["id","serial","collectibleId","ownerId","isTransferable","location","usage","traits","isLocked","lockedByListingId","lockedAt","createdAt","updatedAt","thumbnail","threeDImage"]},"PublicCollectibleListingResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Listing unique identifier"},"collectibleInstanceId":{"type":"string","description":"ID of the collectible instance being listed"},"universalItemId":{"type":"object","description":"Canonical universal item ID for the listed collectible (null for legacy standalone collectibles)","nullable":true},"collectibleInstance":{"description":"The collectible instance being listed","allOf":[{"$ref":"#/components/schemas/PublicCollectibleInstanceResponseDto"}]},"sellerId":{"type":"string","description":"ID of the seller"},"listingType":{"type":"string","description":"Type of listing","enum":["FIXED_PRICE","OFFER_BASED"]},"lixPrice":{"type":"number","description":"Fixed price in LIX (null for offer-based listings)","nullable":true},"startingLixPrice":{"type":"number","description":"Starting price for offers in LIX (null for fixed-price listings)","nullable":true},"status":{"type":"string","description":"Current status of the listing","enum":["ACTIVE","SOLD","CANCELLED"]},"createdAt":{"format":"date-time","type":"string","description":"When this listing was created"},"updatedAt":{"format":"date-time","type":"string","description":"When this listing was last updated"},"soldAt":{"type":"object","description":"When this listing was sold (null if not sold)","nullable":true}},"required":["id","collectibleInstanceId","universalItemId","sellerId","listingType","lixPrice","startingLixPrice","status","createdAt","updatedAt","soldAt"]},"PublicCollectibleTradeResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Trade ID","example":"123e4567-e89b-12d3-a456-426614174000"},"collectibleInstanceId":{"type":"string","description":"Collectible instance ID","example":"123e4567-e89b-12d3-a456-426614174000"},"collectibleInstance":{"description":"Collectible instance details","allOf":[{"$ref":"#/components/schemas/PublicCollectibleInstanceResponseDto"}]},"collectibleId":{"type":"string","description":"Collectible ID","example":"123e4567-e89b-12d3-a456-426614174000"},"collectible":{"description":"Collectible details","allOf":[{"$ref":"#/components/schemas/PublicCollectibleResponseDto"}]},"seller":{"description":"Seller details (public profile)","allOf":[{"$ref":"#/components/schemas/PublicUserResponseDto"}]},"buyer":{"description":"Buyer details (public profile)","allOf":[{"$ref":"#/components/schemas/PublicUserResponseDto"}]},"listingId":{"type":"string","description":"Listing ID","example":"123e4567-e89b-12d3-a456-426614174000"},"listing":{"description":"Listing details","allOf":[{"$ref":"#/components/schemas/PublicCollectibleListingResponseDto"}]},"offerId":{"type":"object","description":"Offer ID","example":"123e4567-e89b-12d3-a456-426614174000","nullable":true},"offer":{"description":"Offer details","nullable":true,"allOf":[{"$ref":"#/components/schemas/PublicCollectibleOfferResponseDto"}]},"grossLixAmount":{"type":"string","description":"Gross LIX amount (total transaction amount)","example":"100.0000"},"tradeType":{"type":"string","description":"Trade type","enum":["INSTANT_BUY","OFFER_ACCEPTED"],"example":"INSTANT_BUY"},"instanceStateAtTrade":{"type":"object","description":"Instance state at the time of trade (JSONB snapshot)","example":{"traits":{"rarity":"legendary"},"usage":{"hoursUsed":10.5,"kmMoved":1500,"damageTaken":5}}},"completedAt":{"format":"date-time","type":"string","description":"Trade completion timestamp","example":"2025-10-28T12:00:00.000Z"}},"required":["id","collectibleInstanceId","collectibleInstance","collectibleId","collectible","seller","buyer","listingId","listing","offerId","offer","grossLixAmount","tradeType","instanceStateAtTrade","completedAt"]},"PublicUniversalItemVersionResponseDto":{"type":"object","properties":{"id":{"type":"string"},"packageId":{"type":"string"},"clientUrl":{"type":"string"},"config":{"type":"object"}},"required":["id","packageId","config"]},"PublicUniversalItemResponseDto":{"type":"object","properties":{"id":{"type":"string"},"packageId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string"},"category":{"type":"string"},"owned":{"type":"boolean"},"wearable":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"latestVersion":{"$ref":"#/components/schemas/PublicUniversalItemVersionResponseDto"}},"required":["id","packageId","name","description","type","category","owned","wearable","tags","latestVersion"]},"PublicUniversalItemsResponseDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicUniversalItemResponseDto"}}},"required":["items"]},"CreateCollectibleBrandRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the brand","example":"Luxury Motors"},"slug":{"type":"string","description":"URL-friendly unique identifier for the brand","example":"luxury-motors"},"description":{"type":"string","description":"Description of the brand","example":"Premium automotive collectibles"},"metadata":{"type":"object","description":"Arbitrary metadata for the brand","example":{"founded":"2023","category":"automotive"}}},"required":["name","slug"]},"CreateCollectibleBrandResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Brand unique identifier"},"creator":{"description":"The creator of this brand","allOf":[{"$ref":"#/components/schemas/BrandCreatorDto"}]},"name":{"type":"string","description":"Brand name","example":"Luxury Motors"},"slug":{"type":"string","description":"URL-friendly unique identifier","example":"luxury-motors"},"description":{"type":"object","description":"Brand description","example":"Premium automotive collectibles","nullable":true},"logo":{"type":"string","description":"Dynamically generated logo URL","example":"https://cdn.example.com/brands/550e8400-e29b-41d4-a716-446655440000/logo"},"metadata":{"type":"object","description":"Arbitrary metadata","example":{"founded":"2023","category":"automotive"}},"createdAt":{"format":"date-time","type":"string","description":"When the brand was created"},"updatedAt":{"format":"date-time","type":"string","description":"When the brand was last updated"},"logoUploadUrl":{"type":"string","description":"Presigned URL for uploading the brand logo","example":"https://cdn.example.com/upload-url"}},"required":["id","creator","name","slug","description","logo","metadata","createdAt","updatedAt","logoUploadUrl"]},"UpdateCollectibleBrandResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Brand unique identifier"},"creator":{"description":"The creator of this brand","allOf":[{"$ref":"#/components/schemas/BrandCreatorDto"}]},"name":{"type":"string","description":"Brand name","example":"Luxury Motors"},"slug":{"type":"string","description":"URL-friendly unique identifier","example":"luxury-motors"},"description":{"type":"object","description":"Brand description","example":"Premium automotive collectibles","nullable":true},"logo":{"type":"string","description":"Dynamically generated logo URL","example":"https://cdn.example.com/brands/550e8400-e29b-41d4-a716-446655440000/logo"},"metadata":{"type":"object","description":"Arbitrary metadata","example":{"founded":"2023","category":"automotive"}},"createdAt":{"format":"date-time","type":"string","description":"When the brand was created"},"updatedAt":{"format":"date-time","type":"string","description":"When the brand was last updated"},"logoUploadUrl":{"type":"string","description":"Presigned URL for uploading the brand logo","example":"https://cdn.example.com/upload-url"}},"required":["id","creator","name","slug","description","logo","metadata","createdAt","updatedAt","logoUploadUrl"]},"UpdateCollectibleBrandRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the brand","example":"Luxury Motors"},"slug":{"type":"string","description":"URL-friendly unique identifier for the brand","example":"luxury-motors"},"description":{"type":"string","description":"Description of the brand","example":"Premium automotive collectibles"},"metadata":{"type":"object","description":"Arbitrary metadata for the brand","example":{"founded":"2023","category":"automotive"}},"collectibleIds":{"description":"Array of collectible IDs to associate with this brand","example":["550e8400-e29b-41d4-a716-446655440000"],"type":"array","items":{"type":"string"}}}},"CreateCollectibleRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"The name/title of the collectible","example":"Ferrari 488"},"slug":{"type":"string","description":"URL-friendly unique identifier for the collectible","example":"ferrari-488"},"description":{"type":"string","description":"Detailed description of the collectible","example":"A high-performance luxury sports car with V8 engine"},"type":{"type":"string","enum":["Wearable","Placeable","Vehicle","Clothing","Accessory","Character","HomeItem","Property"],"description":"Type of collectible","example":"Vehicle"},"tags":{"description":"Array of tags for categorization","example":["car","luxury","italian"],"type":"array","items":{"type":"string"}},"supply":{"type":"number","description":"Number of instances this collectible will have","example":20,"minimum":1,"maximum":10000},"metadata":{"type":"object","description":"Arbitrary metadata (e.g., engine specs, color options)","example":{"engine":"V8","horsepower":661,"weight":1405}},"isUniversal":{"type":"boolean","description":"Whether this collectible works universally across all packages","example":true},"compatiblePackageIds":{"description":"Specific package IDs this collectible is compatible with (if not universal)","example":["pkg-uuid-1","pkg-uuid-2"],"type":"array","items":{"type":"string"}},"isTransferable":{"type":"boolean","description":"Whether instances can be transferred/resold by default","example":true},"previewKeys":{"description":"An array of keys of the collectible previews","example":["Preview_1","Preview_2"],"default":[],"type":"array","items":{"type":"string"}}},"required":["name","slug","description","type","tags","supply","metadata","isUniversal","compatiblePackageIds","isTransferable"]},"CollectibleCreatorDto":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"object","nullable":true}},"required":["id","username","displayName"]},"CollectibleCompatiblePackageDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}},"required":["id","name","slug"]},"CreateCollectibleResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Collectible unique identifier"},"creator":{"description":"The creator/owner of this collectible","allOf":[{"$ref":"#/components/schemas/CollectibleCreatorDto"}]},"creatorId":{"type":"string","description":"Creator ID"},"brandId":{"type":"object","description":"Brand ID (nullable)","nullable":true},"brand":{"description":"The brand associated with this collectible","nullable":true,"allOf":[{"$ref":"#/components/schemas/CollectibleBrandResponseDto"}]},"type":{"type":"string","enum":["Wearable","Placeable","Vehicle","Clothing","Accessory","Character","HomeItem","Property"],"description":"Type of collectible"},"name":{"type":"string","description":"Name of the collectible"},"slug":{"type":"string","description":"URL-friendly unique identifier"},"description":{"type":"string","description":"Description of the collectible"},"tags":{"description":"Tags for categorization","type":"array","items":{"type":"string"}},"supply":{"type":"number","description":"Total number of instances available"},"metadata":{"type":"object","description":"Custom metadata"},"thumbnail":{"type":"object","description":"Thumbnail image URL or key","nullable":true},"thumbnailUploadUrl":{"type":"string","description":"Presigned URL for uploading the thumbnail"},"threeDImage":{"type":"object","description":"3D image URL","nullable":true},"threeDImageUploadUrl":{"type":"string","description":"Presigned URL for uploading the 3D image"},"previews":{"description":"The previews of the collectible","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"isUniversal":{"type":"boolean","description":"Whether this collectible is universally compatible"},"compatiblePackages":{"description":"Compatible packages (if not universal)","type":"array","items":{"$ref":"#/components/schemas/CollectibleCompatiblePackageDto"}},"isTransferable":{"type":"boolean","description":"Whether instances can be transferred by default"},"avgSalePrice":{"type":"number","description":"Average sale price across all trades","example":150.5},"allTimeHighPrice":{"type":"number","description":"All-time highest sale price","example":500},"totalVolumeTraded":{"type":"number","description":"Total volume traded (sum of all sales)","example":3500},"totalSalesCount":{"type":"number","description":"Total number of sales/trades","example":25},"lastSalePrice":{"type":"object","description":"Most recent sale price","example":175,"nullable":true},"lastSaleAt":{"type":"object","description":"Timestamp of the most recent sale","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"When this collectible was created"},"updatedAt":{"format":"date-time","type":"string","description":"When this collectible was last updated"},"previewUploadUrls":{"description":"The upload URLs of the collectible previews","example":["https://example.com/collectible-id/previews/Preview_1","https://example.com/collectible-id/previews/Preview_2"],"type":"array","items":{"type":"string"}}},"required":["id","creator","creatorId","brandId","brand","type","name","slug","description","tags","supply","metadata","thumbnail","threeDImage","previews","isUniversal","compatiblePackages","isTransferable","avgSalePrice","allTimeHighPrice","totalVolumeTraded","totalSalesCount","lastSalePrice","lastSaleAt","createdAt","updatedAt","previewUploadUrls"]},"AddCollectibleInstancesRequestDto":{"type":"object","properties":{"traits":{"type":"object","description":"Instance-specific traits (e.g., color, condition, special attributes)","example":{"color":"red","condition":"pristine","rarity":"legendary"}},"usage":{"type":"object","description":"Initial usage metrics for this instance","example":{"milesUsed":0,"hoursUsed":0,"lastServiced":null}},"previewKeys":{"description":"Preview image keys for this instance","example":["Preview_1","Preview_2","Preview_3"],"type":"array","items":{"type":"string"}}},"required":["traits","usage"]},"AddCollectibleInstanceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Instance unique identifier"},"serial":{"type":"number","description":"Serial number of this instance within the collectible supply"},"collectibleId":{"type":"string","description":"ID of the collectible this instance belongs to"},"collectible":{"description":"The collectible this instance belongs to","allOf":[{"$ref":"#/components/schemas/NestedCollectibleDto"}]},"ownerId":{"type":"object","description":"ID of the current owner (null if not yet claimed)","nullable":true},"owner":{"description":"The user who currently owns this instance. Null when the instance is unowned — clients must render that as unknown, never synthesise a handle from ownerId.","nullable":true,"allOf":[{"$ref":"#/components/schemas/UserSummaryResponseDto"}]},"isTransferable":{"type":"boolean","description":"Whether this specific instance can be transferred"},"location":{"type":"object","description":"Location of this instance (user, server, etc.)","nullable":true},"usage":{"type":"object","description":"Generic usage metrics"},"traits":{"type":"object","description":"Instance-specific traits"},"isLocked":{"type":"boolean","description":"Whether this instance is locked (currently listed on marketplace)"},"lockedByListingId":{"type":"object","description":"ID of the listing that locked this instance (null if not locked)","nullable":true},"lockedAt":{"type":"object","description":"When this instance was locked (null if not locked)","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"When this instance was created"},"updatedAt":{"format":"date-time","type":"string","description":"When this instance was last updated"},"thumbnail":{"type":"string","description":"Thumbnail CDN URL for this instance","example":"https://cdn.example.com/collectibleId/instanceId/thumbnail"},"threeDImage":{"type":"string","description":"3D image CDN URL for this instance","example":"https://cdn.example.com/collectibleId/instanceId/threedimage"},"previews":{"description":"Preview images for this instance","type":"array","items":{"$ref":"#/components/schemas/InstancePreviewDto"}},"activeListing":{"type":"object","description":"Active listing for this instance (if any)","nullable":true},"highestOfferPrice":{"type":"number","description":"Highest offer price for the active listing (if any)","nullable":true,"example":100.5},"thumbnailUploadUrl":{"type":"string","description":"Presigned upload URL for the instance thumbnail","example":"https://r2.example.com/presigned-upload-url?token=xyz&expires=3600"},"threeDImageUploadUrl":{"type":"string","description":"Presigned upload URL for the instance 3D image","example":"https://r2.example.com/presigned-upload-url?token=abc&expires=3600"},"previewUploadUrls":{"description":"Presigned upload URLs for instance preview images","example":["https://r2.example.com/presigned-upload-url?token=def&expires=3600","https://r2.example.com/presigned-upload-url?token=ghi&expires=3600"],"type":"array","items":{"type":"string"}}},"required":["id","serial","collectibleId","ownerId","owner","isTransferable","location","usage","traits","isLocked","lockedByListingId","lockedAt","createdAt","updatedAt","thumbnail","threeDImage","activeListing","highestOfferPrice","thumbnailUploadUrl","threeDImageUploadUrl","previewUploadUrls"]},"ConfirmMediaRequestDto":{"type":"object","properties":{"previewKeys":{"description":"Preview image keys that were uploaded and should be scanned. Omit to scan only the thumbnail and 3D image.","example":["Preview_1","Preview_2"],"type":"array","items":{"type":"string"}}}},"CollectibleResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Collectible unique identifier"},"creator":{"description":"The creator/owner of this collectible","allOf":[{"$ref":"#/components/schemas/CollectibleCreatorDto"}]},"creatorId":{"type":"string","description":"Creator ID"},"brandId":{"type":"object","description":"Brand ID (nullable)","nullable":true},"brand":{"description":"The brand associated with this collectible","nullable":true,"allOf":[{"$ref":"#/components/schemas/CollectibleBrandResponseDto"}]},"type":{"type":"string","enum":["Wearable","Placeable","Vehicle","Clothing","Accessory","Character","HomeItem","Property"],"description":"Type of collectible"},"name":{"type":"string","description":"Name of the collectible"},"slug":{"type":"string","description":"URL-friendly unique identifier"},"description":{"type":"string","description":"Description of the collectible"},"tags":{"description":"Tags for categorization","type":"array","items":{"type":"string"}},"supply":{"type":"number","description":"Total number of instances available"},"metadata":{"type":"object","description":"Custom metadata"},"thumbnail":{"type":"object","description":"Thumbnail image URL or key","nullable":true},"thumbnailUploadUrl":{"type":"string","description":"Presigned URL for uploading the thumbnail"},"threeDImage":{"type":"object","description":"3D image URL","nullable":true},"threeDImageUploadUrl":{"type":"string","description":"Presigned URL for uploading the 3D image"},"previews":{"description":"The previews of the collectible","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"isUniversal":{"type":"boolean","description":"Whether this collectible is universally compatible"},"compatiblePackages":{"description":"Compatible packages (if not universal)","type":"array","items":{"$ref":"#/components/schemas/CollectibleCompatiblePackageDto"}},"isTransferable":{"type":"boolean","description":"Whether instances can be transferred by default"},"avgSalePrice":{"type":"number","description":"Average sale price across all trades","example":150.5},"allTimeHighPrice":{"type":"number","description":"All-time highest sale price","example":500},"totalVolumeTraded":{"type":"number","description":"Total volume traded (sum of all sales)","example":3500},"totalSalesCount":{"type":"number","description":"Total number of sales/trades","example":25},"lastSalePrice":{"type":"object","description":"Most recent sale price","example":175,"nullable":true},"lastSaleAt":{"type":"object","description":"Timestamp of the most recent sale","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"When this collectible was created"},"updatedAt":{"format":"date-time","type":"string","description":"When this collectible was last updated"}},"required":["id","creator","creatorId","brandId","brand","type","name","slug","description","tags","supply","metadata","thumbnail","threeDImage","previews","isUniversal","compatiblePackages","isTransferable","avgSalePrice","allTimeHighPrice","totalVolumeTraded","totalSalesCount","lastSalePrice","lastSaleAt","createdAt","updatedAt"]},"UpdateCollectibleResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Collectible unique identifier"},"creator":{"description":"The creator/owner of this collectible","allOf":[{"$ref":"#/components/schemas/CollectibleCreatorDto"}]},"creatorId":{"type":"string","description":"Creator ID"},"brandId":{"type":"object","description":"Brand ID (nullable)","nullable":true},"brand":{"description":"The brand associated with this collectible","nullable":true,"allOf":[{"$ref":"#/components/schemas/CollectibleBrandResponseDto"}]},"type":{"type":"string","enum":["Wearable","Placeable","Vehicle","Clothing","Accessory","Character","HomeItem","Property"],"description":"Type of collectible"},"name":{"type":"string","description":"Name of the collectible"},"slug":{"type":"string","description":"URL-friendly unique identifier"},"description":{"type":"string","description":"Description of the collectible"},"tags":{"description":"Tags for categorization","type":"array","items":{"type":"string"}},"supply":{"type":"number","description":"Total number of instances available"},"metadata":{"type":"object","description":"Custom metadata"},"thumbnail":{"type":"object","description":"Thumbnail image URL or key","nullable":true},"thumbnailUploadUrl":{"type":"string","description":"Presigned URL for uploading the thumbnail"},"threeDImage":{"type":"object","description":"3D image URL","nullable":true},"threeDImageUploadUrl":{"type":"string","description":"Presigned URL for uploading the 3D image"},"previews":{"description":"The previews of the collectible","type":"array","items":{"$ref":"#/components/schemas/ImageResponseDto"}},"isUniversal":{"type":"boolean","description":"Whether this collectible is universally compatible"},"compatiblePackages":{"description":"Compatible packages (if not universal)","type":"array","items":{"$ref":"#/components/schemas/CollectibleCompatiblePackageDto"}},"isTransferable":{"type":"boolean","description":"Whether instances can be transferred by default"},"avgSalePrice":{"type":"number","description":"Average sale price across all trades","example":150.5},"allTimeHighPrice":{"type":"number","description":"All-time highest sale price","example":500},"totalVolumeTraded":{"type":"number","description":"Total volume traded (sum of all sales)","example":3500},"totalSalesCount":{"type":"number","description":"Total number of sales/trades","example":25},"lastSalePrice":{"type":"object","description":"Most recent sale price","example":175,"nullable":true},"lastSaleAt":{"type":"object","description":"Timestamp of the most recent sale","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"When this collectible was created"},"updatedAt":{"format":"date-time","type":"string","description":"When this collectible was last updated"},"previewUploadUrls":{"description":"The upload URLs of the collectible previews","example":["https://example.com/collectible-id/previews/Preview_1","https://example.com/collectible-id/previews/Preview_2"],"type":"array","items":{"type":"string"}}},"required":["id","creator","creatorId","brandId","brand","type","name","slug","description","tags","supply","metadata","thumbnail","threeDImage","previews","isUniversal","compatiblePackages","isTransferable","avgSalePrice","allTimeHighPrice","totalVolumeTraded","totalSalesCount","lastSalePrice","lastSaleAt","createdAt","updatedAt","previewUploadUrls"]},"UpdateCollectibleRequestDto":{"type":"object","properties":{"name":{"type":"string","description":"The name/title of the collectible","example":"Ferrari 488 GTB"},"slug":{"type":"string","description":"URL-friendly unique identifier for the collectible","example":"ferrari-488-gtb"},"description":{"type":"string","description":"Detailed description of the collectible","example":"A high-performance luxury sports car with upgraded V8 engine"},"type":{"type":"string","enum":["Wearable","Placeable","Vehicle","Clothing","Accessory","Character","HomeItem","Property"],"description":"Type of collectible","example":"Vehicle"},"tags":{"description":"Array of tags for categorization","example":["car","luxury","italian","sports"],"type":"array","items":{"type":"string"}},"supply":{"type":"number","description":"Number of instances this collectible will have (can only be increased, not decreased)","example":25,"minimum":1,"maximum":10000},"metadata":{"type":"object","description":"Arbitrary metadata (e.g., engine specs, color options)","example":{"engine":"V8","horsepower":661,"weight":1405,"topSpeed":330}},"isUniversal":{"type":"boolean","description":"Whether this collectible works universally across all packages","example":true},"compatiblePackageIds":{"description":"Specific package IDs this collectible is compatible with (if not universal)","example":["pkg-uuid-1","pkg-uuid-2"],"type":"array","items":{"type":"string"}},"isTransferable":{"type":"boolean","description":"Whether instances can be transferred/resold by default","example":true},"previewKeys":{"description":"An array of keys of the collectible previews","example":["Preview_1","Preview_2"],"type":"array","items":{"type":"string"}}}},"UpdateCollectibleInstanceResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Instance unique identifier"},"serial":{"type":"number","description":"Serial number of this instance within the collectible supply"},"collectibleId":{"type":"string","description":"ID of the collectible this instance belongs to"},"collectible":{"description":"The collectible this instance belongs to","allOf":[{"$ref":"#/components/schemas/NestedCollectibleDto"}]},"ownerId":{"type":"object","description":"ID of the current owner (null if not yet claimed)","nullable":true},"owner":{"description":"The user who currently owns this instance. Null when the instance is unowned — clients must render that as unknown, never synthesise a handle from ownerId.","nullable":true,"allOf":[{"$ref":"#/components/schemas/UserSummaryResponseDto"}]},"isTransferable":{"type":"boolean","description":"Whether this specific instance can be transferred"},"location":{"type":"object","description":"Location of this instance (user, server, etc.)","nullable":true},"usage":{"type":"object","description":"Generic usage metrics"},"traits":{"type":"object","description":"Instance-specific traits"},"isLocked":{"type":"boolean","description":"Whether this instance is locked (currently listed on marketplace)"},"lockedByListingId":{"type":"object","description":"ID of the listing that locked this instance (null if not locked)","nullable":true},"lockedAt":{"type":"object","description":"When this instance was locked (null if not locked)","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"When this instance was created"},"updatedAt":{"format":"date-time","type":"string","description":"When this instance was last updated"},"thumbnail":{"type":"string","description":"Thumbnail CDN URL for this instance","example":"https://cdn.example.com/collectibleId/instanceId/thumbnail"},"threeDImage":{"type":"string","description":"3D image CDN URL for this instance","example":"https://cdn.example.com/collectibleId/instanceId/threedimage"},"previews":{"description":"Preview images for this instance","type":"array","items":{"$ref":"#/components/schemas/InstancePreviewDto"}},"activeListing":{"type":"object","description":"Active listing for this instance (if any)","nullable":true},"highestOfferPrice":{"type":"number","description":"Highest offer price for the active listing (if any)","nullable":true,"example":100.5},"thumbnailUploadUrl":{"type":"string","description":"Presigned upload URL for the instance thumbnail","example":"https://r2.example.com/presigned-upload-url?token=xyz&expires=3600"},"threeDImageUploadUrl":{"type":"string","description":"Presigned upload URL for the instance 3D image","example":"https://r2.example.com/presigned-upload-url?token=abc&expires=3600"},"previewUploadUrls":{"description":"Presigned upload URLs for instance preview images","example":["https://r2.example.com/presigned-upload-url?token=def&expires=3600","https://r2.example.com/presigned-upload-url?token=ghi&expires=3600"],"type":"array","items":{"type":"string"}}},"required":["id","serial","collectibleId","ownerId","owner","isTransferable","location","usage","traits","isLocked","lockedByListingId","lockedAt","createdAt","updatedAt","thumbnail","threeDImage","activeListing","highestOfferPrice","thumbnailUploadUrl","threeDImageUploadUrl","previewUploadUrls"]},"UpdateCollectibleInstanceRequestDto":{"type":"object","properties":{"traits":{"type":"object","description":"Instance-specific traits (e.g., color, condition, special attributes)","example":{"color":"blue","condition":"good","rarity":"epic"}},"usage":{"type":"object","description":"Usage metrics for this instance","example":{"milesUsed":1500,"hoursUsed":50,"lastServiced":"2025-10-20"}},"isTransferable":{"type":"boolean","description":"Whether this specific instance can be transferred","example":false},"ownerId":{"type":"object","description":"ID of the current owner (Admin can change ownership to any user)","example":"user-uuid-123","nullable":true},"location":{"type":"object","description":"Location of this instance (e.g., {\"type\": \"user\", \"id\": \"user-uuid\"})","example":{"type":"server","id":"server-uuid-456"},"nullable":true},"previewKeys":{"description":"Preview image keys for this instance","example":["Preview_1","Preview_2","Preview_3"],"type":"array","items":{"type":"string"}}}},"CreateListingRequestDto":{"type":"object","properties":{"collectibleInstanceId":{"type":"string","description":"ID of the collectible instance to list","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"listingType":{"type":"string","description":"Type of listing","enum":["FIXED_PRICE","OFFER_BASED"],"example":"FIXED_PRICE"},"lixPrice":{"type":"number","description":"Price in LIX. Required for FIXED_PRICE listings. Optional for OFFER_BASED listings to enable instant buy (must be higher than startingLixPrice).","example":100.5},"startingLixPrice":{"type":"number","description":"Starting price for offers in LIX (required if listing type is OFFER_BASED, must not be present for FIXED_PRICE)","example":50},"allowInstantBuy":{"type":"boolean","description":"Allow instant buy for OFFER_BASED listings (requires lixPrice to be set and higher than startingLixPrice)","example":true,"default":false}},"required":["collectibleInstanceId","listingType"]},"CancelListingRequestDto":{"type":"object","properties":{"listingId":{"type":"string","description":"The UUID of the listing to cancel","example":"123e4567-e89b-12d3-a456-426614174000"}},"required":["listingId"]},"CreateRedeemableCodeRequestDto":{"type":"object","properties":{"userId":{"type":"string","description":"The ID of the user for whom the code is created.","example":"550e8400-e29b-41d4-a716-446655440000"},"type":{"type":"string","description":"The type of the redeemable code.","example":"Test","enum":["Test"]},"amount":{"type":"number","description":"The amount of LIX for this redeemable code.","example":100.5},"expireDate":{"type":"string","description":"The expiration date of the code (ISO 8601 format).","example":"2025-12-31T23:59:59.999Z"}},"required":["userId","type","amount","expireDate"]},"UserMinimalDto":{"type":"object","properties":{"id":{"type":"string","example":"550e8400-e29b-41d4-a716-446655440000"},"username":{"type":"string","example":"john_doe"},"displayName":{"type":"object","example":"John Doe","nullable":true}},"required":["id","username","displayName"]},"RedeemableCodeResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the redeemable code.","example":"550e8400-e29b-41d4-a716-446655440000"},"user":{"description":"The user associated with this code.","allOf":[{"$ref":"#/components/schemas/UserMinimalDto"}]},"type":{"type":"string","description":"The type of the redeemable code.","example":"Test","enum":["Test"]},"amount":{"type":"number","description":"The amount of LIX.","example":100.5},"expireDate":{"format":"date-time","type":"string","description":"The expiration date of the code.","example":"2025-12-31T23:59:59.999Z"},"redeemedAt":{"type":"object","description":"The date when the code was redeemed.","example":"2025-10-07T12:34:56.789Z","nullable":true},"createdAt":{"format":"date-time","type":"string","description":"The creation date of the code.","example":"2025-10-07T10:00:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"The last update date of the code.","example":"2025-10-07T10:00:00.000Z"}},"required":["id","user","type","amount","expireDate","redeemedAt","createdAt","updatedAt"]},"RedeemableCodeCollectionResponseDto":{"type":"object","properties":{"items":{"description":"The items in the collection.","type":"array","items":{"$ref":"#/components/schemas/RedeemableCodeResponseDto"}},"totalItems":{"type":"number","description":"The total number of items in the collection.","example":100},"pagination":{"description":"The pagination information.","allOf":[{"$ref":"#/components/schemas/PaginationResponseDto"}]},"pageInfo":{"description":"Keyset/cursor pagination info for infinite scroll.","allOf":[{"$ref":"#/components/schemas/PageInfoResponseDto"}]}},"required":["items","totalItems","pagination"]},"RedeemCodeRequestDto":{"type":"object","properties":{"code":{"type":"string","description":"The UUID of the redeemable code to redeem.","example":"550e8400-e29b-41d4-a716-446655440000"}},"required":["code"]},"RedeemCodeResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the redemption was successful.","example":true},"transactionId":{"type":"string","description":"The transaction ID from the economy service.","example":"550e8400-e29b-41d4-a716-446655440000"},"amount":{"type":"number","description":"The amount of LIX redeemed.","example":100.5},"newBalance":{"type":"number","description":"The new wallet balance after redemption.","example":250.75},"error":{"type":"string","description":"Error message if redemption failed.","example":null,"nullable":true}},"required":["success","transactionId","amount","newBalance","error"]},"CreatePageDto":{"type":"object","properties":{"title":{"type":"string","description":"The title of the page","example":"About Us","maxLength":255},"slug":{"type":"string","description":"The URL-friendly slug for the page (lowercase, alphanumeric, hyphens only)","example":"about-us","maxLength":255},"content":{"type":"string","description":"The full content of the page","example":"This is the full text of the page..."}},"required":["title","slug","content"]},"PageResponseDto":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"content":{"type":"string"},"versionNumber":{"type":"number"},"createdBy":{"$ref":"#/components/schemas/CreatorDto"},"updatedBy":{"$ref":"#/components/schemas/CreatorDto"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","title","slug","content","versionNumber","createdBy","updatedBy","createdAt","updatedAt"]},"UpdatePageDto":{"type":"object","properties":{"title":{"type":"string","description":"The title of the page","example":"About Us","maxLength":255},"slug":{"type":"string","description":"The URL-friendly slug for the page (lowercase, alphanumeric, hyphens only)","example":"about-us","maxLength":255},"content":{"type":"string","description":"The full content of the page","example":"This is the updated full text of the page..."}}},"Object":{"type":"object","properties":{}},"SendClosedAlphaInvitesResponseDto":{"type":"object","properties":{"message":{"type":"string","description":"Message about the operation","example":"Closed alpha invites are being processed in the background"},"totalEmails":{"type":"number","description":"Total number of emails to process","example":5},"campaignName":{"type":"string","description":"Campaign name","example":"closed-alpha"}},"required":["message","totalEmails","campaignName"]},"SendClosedAlphaInvitesRequestDto":{"type":"object","properties":{"emails":{"description":"Array of email addresses to send closed alpha invites to","example":["user1@example.com","user2@example.com"],"type":"array","items":{"type":"string"}}},"required":["emails"]},"MassEmailLogResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the log","example":"123e4567-e89b-12d3-a456-426614174000"},"recipientEmail":{"type":"string","description":"Email address of the recipient","example":"user@example.com"},"emailContent":{"type":"string","description":"Content of the email sent","example":"Closed Alpha Invite - Code: ABC123"},"campaignName":{"type":"string","description":"Name of the campaign","example":"closed-alpha"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the log was created","example":"2025-12-11T10:30:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the log was last updated","example":"2025-12-11T10:30:00.000Z"}},"required":["id","recipientEmail","emailContent","campaignName","createdAt","updatedAt"]},"CreateServerPlanDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the server plan","example":"Basic Plan","minLength":1,"maxLength":100},"description":{"type":"object","description":"A short description of the plan","example":"Great for small communities and testing","maxLength":500,"nullable":true},"slug":{"type":"string","description":"URL-friendly unique identifier for the plan","example":"basic-plan","minLength":1,"maxLength":100},"lixPrice":{"type":"number","description":"Price in LIX for this plan","example":100,"minimum":0},"cpuCores":{"type":"number","description":"Number of CPU cores allocated","example":2,"minimum":1},"ramMb":{"type":"number","description":"RAM in MB","example":4096,"minimum":512},"storageMb":{"type":"number","description":"Storage in MB","example":51200,"minimum":1024},"trafficLimitMb":{"type":"object","description":"Traffic limit in MB per billing period. Use null for unlimited traffic","example":102400,"minimum":0,"nullable":true},"monthlyAvailable":{"type":"boolean","description":"Whether monthly billing is available for this plan","example":true,"default":true},"availableRegions":{"description":"Available regions for this plan","example":["us-east","eu-west","asia-pacific"],"default":[],"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean","description":"Whether this plan is active and available for purchase","example":true,"default":true},"vultrPlanId":{"type":"string","description":"Vultr plan ID that corresponds to this server plan","example":"vhp-4c-8gb-amd","maxLength":50},"ovhPlanId":{"type":"string","description":"OVH plan ID that corresponds to this server plan","example":"d2-4","maxLength":50}},"required":["name","slug","lixPrice","cpuCores","ramMb","storageMb"]},"UpdateServerPlanDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the server plan","example":"Basic Plan","minLength":1,"maxLength":100},"description":{"type":"object","description":"A short description of the plan","example":"Great for small communities and testing","maxLength":500,"nullable":true},"slug":{"type":"string","description":"URL-friendly unique identifier for the plan","example":"basic-plan","minLength":1,"maxLength":100},"lixPrice":{"type":"number","description":"Price in LIX for this plan","example":100,"minimum":0},"cpuCores":{"type":"number","description":"Number of CPU cores allocated","example":2,"minimum":1},"ramMb":{"type":"number","description":"RAM in MB","example":4096,"minimum":512},"storageMb":{"type":"number","description":"Storage in MB","example":51200,"minimum":1024},"trafficLimitMb":{"type":"object","description":"Traffic limit in MB per billing period. Use null for unlimited traffic","example":102400,"minimum":0,"nullable":true},"monthlyAvailable":{"type":"boolean","description":"Whether monthly billing is available for this plan","example":true},"availableRegions":{"description":"Available regions for this plan","example":["us-east","eu-west","asia-pacific"],"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean","description":"Whether this plan is active and available for purchase","example":true},"vultrPlanId":{"type":"object","description":"Vultr plan ID that corresponds to this server plan","example":"vhp-4c-8gb-amd","maxLength":50},"ovhPlanId":{"type":"object","description":"OVH plan ID that corresponds to this server plan","example":"d2-4","maxLength":50}}},"VultrRegionResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the region (e.g., \"ams\", \"ewr\")","example":"ams"},"city":{"type":"string","description":"City name where the region is located","example":"Amsterdam"},"country":{"type":"string","description":"Country name where the region is located","example":"NL"},"continent":{"type":"string","description":"Continent where the region is located","example":"Europe"},"options":{"description":"Available options/features for this region","example":["ddos_protection","block_storage_high_perf"],"type":"array","items":{"type":"string"}}},"required":["id","city","country","continent","options"]},"VultrAvailabilityResponseDto":{"type":"object","properties":{"availablePlans":{"description":"List of available compute plan IDs in this region","example":["vc2-1c-1gb","vc2-1c-2gb","vc2-2c-4gb"],"type":"array","items":{"type":"string"}}},"required":["availablePlans"]},"ConnectResponseDto":{"type":"object","properties":{"url":{"type":"string","description":"Discord OAuth authorization URL","example":"https://discord.com/oauth2/authorize?client_id=..."},"state":{"type":"string","description":"State parameter for OAuth security validation","example":"550e8400-e29b-41d4-a716-446655440000"}},"required":["url","state"]},"SetDataStoreEntryDto":{"type":"object","properties":{"value":{"type":"object","description":"The value to store. Any JSON-serializable value (object, array, string, number, boolean). Falsy values (0, false, \"\") are allowed.","example":{"score":100,"level":5}},"expectedVersion":{"type":"number","description":"Optional optimistic-concurrency version. Pass the version you last read to detect conflicting writes; pass 0 to assert create-only (fail if the key already exists).","example":3}},"required":["value"]},"IncrementDataStoreEntryDto":{"type":"object","properties":{"fields":{"type":"object","description":"Counter fields to move, as name -> whole-number delta (negative to subtract). Applied atomically, so concurrent increments cannot lose each other.","example":{"gems":5,"votesYes":1}}},"required":["fields"]},"SubmitScoreDto":{"type":"object","properties":{"score":{"type":"number","description":"The score to submit. Kept only if it beats the stored best for this player on this board (see order).","example":1200},"subject":{"type":"string","description":"The player the score belongs to. Required for a game server or creator token; ignored on a world session, which always submits its own score."},"displayName":{"type":"string","description":"Name to show beside the score on the board. Trimmed to 64 characters; keeps the last submitted name when omitted.","example":"Astro"},"order":{"type":"string","description":"Which end of the board wins: \"desc\" keeps the highest score (default), \"asc\" the lowest (lap times).","enum":["asc","desc"]},"size":{"type":"number","description":"How many entries the board keeps (1-100). Defaults to 100; a submit past the cutoff of a full board is a no-op.","example":100}},"required":["score"]},"WaitlistEntryResponseDto":{"type":"object","properties":{"accepted":{"type":"boolean","description":"Whether the submission was accepted","example":true},"message":{"type":"string","description":"Generic confirmation message to avoid account enumeration","example":"Your request has been received."}},"required":["accepted","message"]},"CreateWaitlistEntryDto":{"type":"object","properties":{"email":{"type":"string","description":"Email address to add to the waitlist","example":"player@example.com","maxLength":255},"source":{"type":"string","description":"Optional source tag to identify integration origin (web, landing page, campaign)","example":"web","maxLength":32}},"required":["email"]},"LauncherProductResponseDto":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"executablePath":{"type":"string"},"description":{"type":"object","nullable":true},"bannerUrl":{"type":"object","nullable":true},"imageUrls":{"type":"array","items":{"type":"string"}},"ignoredPaths":{"description":"POSIX path prefixes excluded from publish/install/verify/repair.","type":"array","items":{"type":"string"}},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","slug","name","executablePath","imageUrls","ignoredPaths","createdAt","updatedAt"]},"LauncherBranchResponseDto":{"type":"object","properties":{"id":{"type":"string"},"productId":{"type":"string"},"productSlug":{"type":"string"},"name":{"type":"string"},"description":{"type":"object","nullable":true},"isDefault":{"type":"boolean","description":"Whether this is the default branch for the product."},"currentBuildId":{"type":"object","nullable":true,"description":"launcher_builds.id of the build the branch currently points to, or null if no build has been promoted yet."},"currentBuildVersion":{"type":"object","nullable":true,"description":"Human-readable version slug from the build the branch currently points to (e.g. \"2026.05.14-1200\"), or null if no build has been promoted yet. Sourced from launcher_builds.build_id.","example":"2026.05.14-1200"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","productId","productSlug","name","description","isDefault","currentBuildId","currentBuildVersion","updatedAt"]},"ManifestResponseDto":{"type":"object","properties":{"manifest":{"type":"object","description":"Parsed manifest JSON as published by the CLI. Schema: see launcher PROJECT_DESCRIPTION Section 6."},"manifestHash":{"type":"string","description":"SHA-256 hash of the manifest body (64-char lowercase hex). Pass this to POST chunk-urls to request presigned download URLs for specific chunks.","example":"a1b2c3d4e5f6071829304a5b6c7d8e9fa0b1c2d3e4f50617283940a1b2c3d4e5","minLength":64,"maxLength":64},"buildVersion":{"type":"string","description":"Human-readable version string of the build being served (sourced from launcher_builds.build_id, e.g. \"2026.05.14-1200\").","example":"2026.05.14-1200"},"patchNotes":{"type":"object","nullable":true,"description":"Markdown patch notes for this build as set by an admin. Null when no notes have been published."}},"required":["manifest","manifestHash","buildVersion","patchNotes"]},"ChunkUrlDto":{"type":"object","properties":{"hash":{"type":"string","description":"Lowercase hex SHA-256 of the chunk this URL fetches."},"url":{"type":"string","description":"Presigned R2 GET URL. Valid until expiresAt."},"expiresAt":{"format":"date-time","type":"string","description":"ISO-8601 timestamp at which the URL stops being valid."},"size":{"type":"number","description":"Chunk size in bytes, as declared in the v2 manifest. Clients use this for disk-space planning and progress reporting before fetching.","example":4194304}},"required":["hash","url","expiresAt","size"]},"ChunkUrlsResponseDto":{"type":"object","properties":{"urls":{"description":"Presigned R2 GET URLs for the requested chunk hashes. Hashes not present in the manifest are silently omitted.","type":"array","items":{"$ref":"#/components/schemas/ChunkUrlDto"}}},"required":["urls"]},"GetChunkUrlsRequestDto":{"type":"object","properties":{"manifestHash":{"type":"string","description":"Manifest hash to validate against — must match the current build for this branch. Obtain this from the manifest body endpoint.","minLength":64,"maxLength":64,"example":"a1b2c3d4e5f6071829304a5b6c7d8e9fa0b1c2d3e4f50617283940a1b2c3d4e5"},"chunkHashes":{"description":"Chunk hashes (lowercase hex SHA-256, 64 chars each) to generate presigned download URLs for. Maximum 5 000 per request. Hashes not present in the manifest are silently omitted from the response.","minItems":1,"maxItems":5000,"type":"array","items":{"type":"string"}}},"required":["manifestHash","chunkHashes"]},"LauncherBranchAdminResponseDto":{"type":"object","properties":{"id":{"type":"string"},"productId":{"type":"string"},"productSlug":{"type":"string","description":"Slug of the product this branch belongs to."},"productName":{"type":"string","description":"Display name of the product this branch belongs to."},"name":{"type":"string","description":"Branch name slug (e.g. \"main\", \"test\", \"playtest-2026\")."},"description":{"type":"object","nullable":true},"isDefault":{"type":"boolean","description":"Whether this is the default branch for the product."},"deletedAt":{"type":"object","nullable":true,"description":"Populated when the branch is archived."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","productId","productSlug","productName","name","isDefault","createdAt","updatedAt"]},"CreateLauncherBranchDto":{"type":"object","properties":{"productSlug":{"type":"string","description":"Slug of the product this branch belongs to.","example":"main-game"},"name":{"type":"string","description":"Branch name slug. Lowercase alphanumeric and hyphens only. Immutable after creation.","example":"playtest-2026"},"description":{"type":"string","description":"Optional description of the branch purpose."}},"required":["productSlug","name"]},"UpdateLauncherBranchDto":{"type":"object","properties":{"description":{"type":"string","description":"Optional description of the branch purpose."}}},"PromoteBranchResponseDto":{"type":"object","properties":{"previousBuildId":{"type":"object","description":"The build the branch pointed to before this promotion. Null on the first ever promotion of the branch.","nullable":true},"currentBuildId":{"type":"string","description":"The build the branch now points to."},"promotedAt":{"format":"date-time","type":"string","description":"Timestamp recorded on the audit row."}},"required":["previousBuildId","currentBuildId","promotedAt"]},"PromoteBranchDto":{"type":"object","properties":{"buildId":{"type":"string","description":"launcher_builds.id (the UUID PK), not the human-readable buildId string.","example":"a00db5c3-73b8-4f92-b7cd-7ee843b16dc3"},"reason":{"type":"string","description":"Optional admin note for the audit log (e.g. \"rolling back due to crash spike\").","maxLength":500}},"required":["buildId"]},"LauncherBuildPromotedBranchDto":{"type":"object","properties":{"id":{"type":"string","description":"Branch UUID."},"name":{"type":"string","description":"Branch name (e.g. \"stable\", \"beta\")."}},"required":["id","name"]},"LauncherBuildAdminResponseDto":{"type":"object","properties":{"id":{"type":"string"},"productId":{"type":"string"},"productSlug":{"type":"string","description":"Slug of the product this build belongs to."},"buildId":{"type":"string","description":"Human-readable version string (e.g. \"2026.05.14-1200\"). This is the buildId column, not the UUID primary key."},"platform":{"type":"string","description":"Target platform (e.g. \"win64\", \"macos\")."},"status":{"type":"string","enum":["pending","finalized"]},"manifestUrl":{"type":"object","nullable":true},"manifestHash":{"type":"object","nullable":true},"totalSize":{"type":"number"},"totalFiles":{"type":"object","nullable":true},"patchNotes":{"type":"object","nullable":true,"description":"Markdown patch notes for this build. Max 50 000 characters."},"createdById":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"promotedBranches":{"description":"Branches whose live pointer currently targets this build (i.e. the branches this build is currently promoted to).","type":"array","items":{"$ref":"#/components/schemas/LauncherBuildPromotedBranchDto"}}},"required":["id","productId","productSlug","buildId","platform","status","totalSize","createdById","createdAt","promotedBranches"]},"UpdateLauncherBuildDto":{"type":"object","properties":{"patchNotes":{"type":"object","description":"Markdown patch notes for this build. Pass null to clear existing notes. Max 50 000 characters.","nullable":true,"maxLength":50000}}},"OpenBuildResponseDto":{"type":"object","properties":{"launcherBuildId":{"type":"string","description":"UUID of the newly created (pending) launcher build row. Pass this as :buildId to register-chunks and finalize."},"manifestUploadUrl":{"type":"string","description":"Presigned PUT URL for uploading manifest.json. Valid for 1 hour. Upload the manifest after all chunks are uploaded, then call finalize."},"expiresAt":{"format":"date-time","type":"string","description":"ISO 8601 datetime at which the manifestUploadUrl expires.","example":"2026-05-11T19:00:00.000Z"}},"required":["launcherBuildId","manifestUploadUrl","expiresAt"]},"OpenBuildDto":{"type":"object","properties":{"productId":{"type":"string","description":"UUID of the launcher product this build belongs to.","example":"a00db5c3-73b8-4f92-b7cd-7ee843b16dc3"},"buildId":{"type":"string","description":"Human-readable build identifier from the publishing CLI.","example":"2026.04.21-1145","maxLength":64},"platform":{"type":"string","description":"Target platform for this build.","example":"win64","maxLength":32},"totalChunks":{"type":"number","description":"Total number of unique content chunks expected across all register-chunks batches.","example":11245,"minimum":1},"totalBytes":{"type":"number","description":"Total build size in bytes.","example":32212254720,"minimum":1}},"required":["productId","buildId","platform","totalChunks","totalBytes"]},"ChunkUploadDto":{"type":"object","properties":{"hash":{"type":"string","description":"SHA-256 hex of the chunk this entry refers to."},"uploadUrl":{"type":"object","description":"Presigned PUT URL for uploading this chunk. Null when alreadyExists is true.","nullable":true},"alreadyExists":{"type":"boolean","description":"True if R2 already has this content. CLI must skip uploading."}},"required":["hash","uploadUrl","alreadyExists"]},"RegisterChunksResponseDto":{"type":"object","properties":{"chunkUploads":{"description":"One entry per hash from the request, in the same order as the input.","type":"array","items":{"$ref":"#/components/schemas/ChunkUploadDto"}}},"required":["chunkUploads"]},"ChunkRegistrationDto":{"type":"object","properties":{"hash":{"type":"string","description":"Lowercase hex SHA-256 of the chunk content (64 characters).","example":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},"size":{"type":"number","description":"Chunk size in bytes. Must be at least 1 and at most 16 MiB (FastCDC maximum).","example":4194304,"minimum":1,"maximum":16777216}},"required":["hash","size"]},"RegisterChunksDto":{"type":"object","properties":{"chunks":{"description":"Chunks to register in this batch. Each entry carries a SHA-256 hash and byte size. Maximum 5 000 per request. Re-posting the same chunks returns fresh upload URLs — use this to refresh expired URLs without a separate endpoint.","type":"array","items":{"$ref":"#/components/schemas/ChunkRegistrationDto"}}},"required":["chunks"]},"FinalizeBuildDto":{"type":"object","properties":{"manifestHash":{"type":"string","description":"Lowercase hex SHA-256 of the uploaded manifest JSON.","example":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},"totalFiles":{"type":"number","description":"Total number of files described in the build manifest.","example":4321,"minimum":0}},"required":["manifestHash","totalFiles"]},"LauncherBuildResponseDto":{"type":"object","properties":{"id":{"type":"string"},"productId":{"type":"string"},"buildId":{"type":"string"},"platform":{"type":"string"},"status":{"type":"string","enum":["pending","finalized"]},"manifestUrl":{"type":"string"},"manifestHash":{"type":"string"},"totalSize":{"type":"number"},"totalFiles":{"type":"number"},"createdBy":{"$ref":"#/components/schemas/CreatorDto"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","productId","buildId","platform","status","manifestUrl","manifestHash","totalSize","totalFiles","createdBy","createdAt"]},"InstallerUploadUrlResponseDto":{"type":"object","properties":{"upload_url":{"type":"string","description":"Presigned R2 PUT URL. Upload the artifact directly to this URL using an HTTP PUT request with the Content-Type header matching the requested content_type. Valid for 1 hour.","example":"https://<account>.r2.cloudflarestorage.com/launcher-installer/HELIX-Launcher-Setup-1.2.3.exe?..."},"public_url":{"type":"string","description":"Public CDN URL at which the artifact will be accessible after upload.","example":"https://eu.launcher-installer.dev.helix-cdn.com/HELIX-Launcher-Setup-1.2.3.exe"},"expires_in":{"type":"number","description":"Seconds until the presigned upload_url expires.","example":3600}},"required":["upload_url","public_url","expires_in"]},"InstallerUploadUrlRequestDto":{"type":"object","properties":{"filename":{"type":"string","description":"Filename of the artifact to upload. Must be a valid launcher installer filename: a versioned .exe or .exe.blockmap (e.g. HELIX-Launcher-Setup-1.2.3.exe), or an Electron-builder update manifest (latest.yml / latest-mac.yml).","example":"HELIX-Launcher-Setup-1.2.3.exe"},"content_type":{"type":"string","description":"MIME type of the artifact.","enum":["application/octet-stream","application/x-yaml","text/yaml"],"example":"application/octet-stream"}},"required":["filename","content_type"]},"LauncherProductAdminResponseDto":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"executablePath":{"type":"string"},"description":{"type":"object","nullable":true},"bannerKey":{"type":"object","nullable":true},"imageKeys":{"type":"array","items":{"type":"string"}},"ignoredPaths":{"description":"POSIX path prefixes excluded from publish/install/verify/repair.","type":"array","items":{"type":"string"}},"bannerUrl":{"type":"object","nullable":true},"imageUrls":{"type":"array","items":{"type":"string"}},"deletedAt":{"type":"object","nullable":true,"description":"Populated when the product is archived."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","slug","name","executablePath","imageKeys","ignoredPaths","imageUrls","createdAt","updatedAt"]},"CreateLauncherProductDto":{"type":"object","properties":{"slug":{"type":"string","description":"Unique human-readable slug. Lowercase alphanumeric and hyphens only.","example":"main-game"},"name":{"type":"string","description":"Display name shown in the launcher.","example":"Main Game"},"executablePath":{"type":"string","description":"Path to the game executable relative to the install root.","example":"bin/Game.exe"},"description":{"type":"string","description":"Markdown product description."},"bannerKey":{"type":"string","description":"Filename of the banner image (e.g. \"banner.jpg\"). A presigned R2 PUT URL is returned in uploadUrls.banner.","example":"banner.jpg"},"imageKeys":{"description":"Ordered list of gallery image filenames. Max 10, all unique. Presigned R2 PUT URLs are returned in uploadUrls.images in the same order.","example":["screenshot1.jpg","screenshot2.png"],"type":"array","items":{"type":"string"}},"ignoredPaths":{"description":"POSIX path prefixes (e.g. \"SandboxGame/Saved\") to exclude from publish, install, verify, and repair operations. Max 50 entries. Backslashes and trailing slashes are normalized automatically.","maxItems":50,"example":["SandboxGame/Saved","Engine/Saved"],"type":"array","items":{"type":"string"}}},"required":["slug","name","executablePath"]},"LauncherProductUploadUrlsDto":{"type":"object","properties":{"banner":{"type":"string","description":"Presigned R2 PUT URL for the banner image."},"images":{"description":"Presigned R2 PUT URLs for gallery images, in the same order as imageKeys.","type":"array","items":{"type":"string"}}}},"LauncherProductWithUploadUrlsResponseDto":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"executablePath":{"type":"string"},"description":{"type":"object","nullable":true},"bannerKey":{"type":"object","nullable":true},"imageKeys":{"type":"array","items":{"type":"string"}},"ignoredPaths":{"description":"POSIX path prefixes excluded from publish/install/verify/repair.","type":"array","items":{"type":"string"}},"bannerUrl":{"type":"object","nullable":true},"imageUrls":{"type":"array","items":{"type":"string"}},"deletedAt":{"type":"object","nullable":true,"description":"Populated when the product is archived."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"uploadUrls":{"$ref":"#/components/schemas/LauncherProductUploadUrlsDto"}},"required":["id","slug","name","executablePath","imageKeys","ignoredPaths","imageUrls","createdAt","updatedAt","uploadUrls"]},"UpdateLauncherProductDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name shown in the launcher.","example":"Main Game"},"executablePath":{"type":"string","description":"Path to the game executable relative to the install root.","example":"bin/Game.exe"},"description":{"type":"string","description":"Markdown product description."},"bannerKey":{"type":"object","description":"Filename of the banner image. Pass null to clear the banner. A presigned R2 PUT URL is returned in uploadUrls.banner when a non-null value is provided.","nullable":true,"example":"banner.jpg"},"imageKeys":{"description":"Ordered list of gallery image filenames. Replaces the full set. Max 10, all unique. Presigned R2 PUT URLs are returned in uploadUrls.images in the same order.","example":["screenshot1.jpg","screenshot2.png"],"type":"array","items":{"type":"string"}},"ignoredPaths":{"description":"POSIX path prefixes to exclude from publish, install, verify, and repair operations. Replaces the full set. Max 50 entries. Backslashes and trailing slashes are normalized automatically.","maxItems":50,"example":["SandboxGame/Saved","Engine/Saved"],"type":"array","items":{"type":"string"}}}},"SsoExchangeRequestDto":{"type":"object","properties":{"code":{"type":"string","description":"The one-time exchange code received from the SSO callback redirect.","example":"123e4567-e89b-12d3-a456-426614174000"}},"required":["code"]},"SsoCompletionPrefillDto":{"type":"object","properties":{"provider":{"type":"string","description":"The SSO provider.","example":"google"},"email":{"type":"object","description":"Email reported by the provider, if any.","nullable":true},"emailRequired":{"type":"boolean","description":"True when the provider did not supply an email and the user must enter one."},"suggestedUsername":{"type":"object","description":"Username suggestion derived from the provider profile.","nullable":true},"displayName":{"type":"object","description":"Display name reported by the provider, if any.","nullable":true},"inviteRequired":{"type":"boolean","description":"True when an invite code is required to finish signup."}},"required":["provider","email","emailRequired","suggestedUsername","displayName","inviteRequired"]},"SsoExchangeResponseDto":{"type":"object","properties":{"status":{"type":"string","description":"Result status.","enum":["ok","completion_required","verification_required"]},"access_token":{"type":"string"},"refresh_token":{"type":"string"},"token_type":{"type":"string","example":"Bearer"},"expires_in":{"type":"number","example":3600},"refresh_expires_in":{"type":"number","example":1209600},"completion_token":{"type":"string","description":"Token to pass to /auth/sso/complete."},"prefill":{"$ref":"#/components/schemas/SsoCompletionPrefillDto"}},"required":["status"]},"SsoCompleteRequestDto":{"type":"object","properties":{"completion_token":{"type":"string","description":"The completion token returned by the exchange endpoint.","example":"123e4567-e89b-12d3-a456-426614174000"},"username":{"type":"string","description":"The username for the new account.","example":"exampleuser1","minLength":5,"maxLength":24},"email":{"type":"string","description":"Email for the new account. Only required when the SSO provider did not supply one.","example":"user@example.com"},"inviteCode":{"type":"string","description":"The invite code required to register (6-character alphanumeric). Required when ENABLE_INVITE_CODES is true.","example":"ABC123"},"acceptedEulaId":{"type":"string","description":"The UUID of the EULA that the user has accepted. Must be the latest version."},"acceptedPrivacyPolicyId":{"type":"string","description":"The UUID of the Privacy Policy that the user has accepted. Must be the latest version."},"acceptedLatestFlag":{"type":"boolean","description":"Flag to automatically accept the latest EULA and Privacy Policy.","default":false}},"required":["completion_token","username"]},"SsoIdentityDto":{"type":"object","properties":{"provider":{"type":"string","example":"google"},"email":{"type":"object","nullable":true},"displayName":{"type":"object","nullable":true},"connectedAt":{"format":"date-time","type":"string"}},"required":["provider","email","displayName","connectedAt"]},"SsoIdentitiesResponseDto":{"type":"object","properties":{"identities":{"type":"array","items":{"$ref":"#/components/schemas/SsoIdentityDto"}},"hasPassword":{"type":"boolean","description":"True when the account has a password (relevant for unlink lockout rules)."}},"required":["identities","hasPassword"]},"SsoStartLinkResponseDto":{"type":"object","properties":{"url":{"type":"string","description":"Provider authorization URL to open."}},"required":["url"]},"RuntimeFileDto":{"type":"object","properties":{"path":{"type":"string","description":"Bundle-relative path under a runtime category (e.g. three/0.172.0/three.module.js)."},"size":{"type":"number","minimum":1,"maximum":26214400}},"required":["path","size"]},"CreateRuntimeUploadRequestDto":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/RuntimeFileDto"}}},"required":["files"]},"AchievementCriteriaDto":{"type":"object","properties":{"signal":{"type":"string","enum":["analytics","iwp","playtime","datastore"],"description":"analytics = count of an analytics event in this world; iwp = successful in-world purchases (count or LIX); playtime = seconds in this world; datastore = a numeric field inside a per-user data-store document."},"op":{"type":"string","enum":["gte","lte","eq"]},"value":{"type":"number","description":"Threshold the measured value is compared against."},"eventName":{"type":"string","enum":["user_signed_up","user_logged_in","anonymous_user_identified","invite_sent","invite_link_copied","invite_landed","invite_modal_viewed","invite_opened","invite_accepted","invite_signup_started","invite_signup_completed","invite_reward_granted","invite_reward_denied","referral_source_captured","ftue_started","ftue_step_started","ftue_step_viewed","ftue_step_completed","ftue_step_skipped","ftue_deep_link_destination_entered","ftue_tablet_opened","ftue_hud_minimized","ftue_hud_expanded","ftue_hud_dismissed","ftue_welcome_notification_sent","ftue_reward_claimed","ftue_item_placed","ftue_showcase_home_visited","ftue_item_scanned","ftue_world_joined","ftue_world_objective_completed","ftue_friend_edge_created","ftue_invite_link_copied","ftue_currencies_learned","ftue_item_purchased","ftue_first_post","ftue_creation_published","ftue_completed","ftue_abandoned","session_started","session_ended","world_entered","world_loaded","world_load_failed","world_exited","world_heartbeat","instance_joined","instance_left","friend_request_sent","friend_request_accepted","party_created","party_joined","share_clicked","item_viewed","item_purchased","item_equipped","home_visited","creator_product_viewed","creator_product_purchased","creator_earned","lix_spent","coins_spent","report_submitted","moderation_action_created","content_rating_changed","trust_state_changed","client_error_seen","api_error_seen","developer_publish_cta_clicked","developer_publish_modal_viewed","developer_publish_path_selected","developer_install_command_copied","developer_publish_prompt_copied"],"description":"Required for `analytics`: which event to count."},"key":{"type":"string","description":"Required for `datastore`: which per-user document to read — one of player:{userId}, mp:player:{userId}.","example":"player:{userId}"},"field":{"type":"string","description":"Required for `datastore`: dot-path to the number inside the document at `key` (e.g. \"stats.summits\"). For `mp:player:{userId}` it names the persistent playerVar.","example":"summits"},"metric":{"type":"string","enum":["count","lix"],"description":"`iwp` only: purchase count (default) or total LIX spent."}},"required":["signal","op","value"]},"CreateAchievementRequestDto":{"type":"object","properties":{"worldId":{"type":"string","description":"World to register under. Omit for a platform (FTUE/meta) achievement — admin only."},"key":{"type":"string","description":"Stable namespaced identifier (a-z0-9_-), unique within the world (or platform).","example":"first_summit"},"name":{"type":"string","example":"First Summit"},"description":{"type":"string","example":"Reach the peak of the mountain world."},"points":{"type":"number","description":"Steam-style points (summed into gamerscore).","default":0},"hidden":{"type":"boolean","description":"Hidden achievements show \"???\" until earned.","default":false},"unlockMode":{"type":"string","enum":["room","criteria","platform"],"default":"platform","description":"Who may award this achievement. `room` = the authoritative multiplayer room server (unforgeable). `criteria` = the backend, by evaluating `criteria` against evidence it owns (`datastore`/`iwp` within seconds of the change; the aggregate `analytics`/`playtime` signals on the hourly sweep). `platform` = first-party platform code. There is no client-attested mode: a browser world cannot award its own achievements."},"criteria":{"description":"Required when `unlockMode` is `criteria`. Sent as a JSON string on the multipart form.","allOf":[{"$ref":"#/components/schemas/AchievementCriteriaDto"}]}},"required":["key","name"]},"UpdateAchievementRequestDto":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"points":{"type":"number"},"hidden":{"type":"boolean"},"active":{"type":"boolean"}}},"GrantAchievementRequestDto":{"type":"object","properties":{"userId":{"type":"string","description":"The user who earns the achievement."},"worldId":{"type":"string","description":"Optional world-scope assertion: the caller declares which world it is; must match the achievement’s world or the grant is refused."},"reason":{"type":"string","description":"Free-text reason recorded on the ledger."}},"required":["userId"]},"DreamerGenerateRequestDto":{"type":"object","properties":{"kind":{"type":"string","enum":["avatar","home_item"]},"prompt":{"type":"string"},"additionalPrompt":{"type":"string"},"title":{"type":"string"},"projectId":{"type":"string"},"category":{"type":"string","enum":["wearable","jackets","tops","bottoms","footwear","accessories","hair","makeup","body","furniture","decor","lighting","structure","utility","interactable","vehicle","collectible","misc"]},"contentRating":{"type":"string"},"priceLix":{"type":"object","nullable":true},"collectible":{"type":"boolean"},"supply":{"type":"object","nullable":true},"dimensionsMeters":{"type":"object"},"targetPolycount":{"type":"number"},"allowOversize":{"type":"boolean"}},"required":["kind","prompt"]},"DreamerApproveRequestDto":{"type":"object","properties":{"gate":{"type":"string","enum":["concept","preview"]}},"required":["gate"]},"DreamerReviseRequestDto":{"type":"object","properties":{"gate":{"type":"string","enum":["concept","preview"]},"prompt":{"type":"string"}},"required":["gate"]},"DreamerPublishJobRequestDto":{"type":"object","properties":{}},"DreamerAssetGenerationSourceDto":{"type":"object","properties":{"mode":{"type":"string","enum":["text","reference"],"default":"text"},"referenceId":{"type":"string","format":"uuid","description":"Required only for reference mode. Returned by POST /api/v1/dreamer/assets/references."}},"required":["mode"]},"DreamerAudioVoiceSettingsDto":{"type":"object","properties":{"stability":{"type":"number","minimum":0,"maximum":1},"similarityBoost":{"type":"number","minimum":0,"maximum":1},"style":{"type":"number","minimum":0,"maximum":1},"speed":{"type":"number","minimum":0.7,"maximum":1.2,"description":"Conservative product range around the vendor default of 1.0."},"speakerBoost":{"type":"boolean"}}},"DreamerAssetGenerateRequestDto":{"type":"object","properties":{"kind":{"type":"string","enum":["image","texture","prop","character","material","audio","gaussian_splat","animation"]},"source":{"description":"Defaults to text. Reference mode binds this draft to one validated creator-owned staged upload.","allOf":[{"$ref":"#/components/schemas/DreamerAssetGenerationSourceDto"}]},"prompt":{"type":"string","maxLength":4100,"description":"Required for every generation except text_to_speech audio, which uses text. Music allows 4,100 characters; every other mode allows 3,000."},"additionalPrompt":{"type":"string"},"title":{"type":"string","description":"Optional display name for an environment generation."},"style":{"type":"string","enum":["realistic","stylized","low_poly","voxel"],"description":"Prop/character only. A curated prompt modifier, not a vendor model id."},"skeleton":{"type":"string","enum":["humanoid"],"description":"Character only. Humanoid is the only generation skeleton currently available."},"loop":{"type":"boolean","description":"Audio only: request a seamless loop."},"durationSeconds":{"type":"number","minimum":0.5,"maximum":600,"description":"Audio only: requested duration in seconds. Sound effects allow 0.5-30s; music allows 3-600s — the precise per-mode range is enforced server-side."},"audioMode":{"type":"string","enum":["sound_effect","music","text_to_speech"],"default":"sound_effect","description":"Audio only: which ElevenLabs-backed mode to generate."},"model":{"type":"string","description":"Audio only: an allowlisted vendor model id for the selected audioMode (validated server-side)."},"outputFormat":{"type":"string","description":"Audio only: a portable MP3 output-format enum value, e.g. \"mp3_44100_128\"."},"promptInfluence":{"type":"number","minimum":0,"maximum":1,"description":"Sound effect only: how closely to follow the prompt."},"forceInstrumental":{"type":"boolean","description":"Music only: request an instrumental-only composition."},"text":{"type":"string","maxLength":40000,"description":"Text-to-speech only: the text to convert to speech."},"voiceId":{"type":"string","description":"Text-to-speech only: the ElevenLabs voice id to speak with."},"languageCode":{"type":"string","description":"Text-to-speech only: ISO 639-1 language code."},"seed":{"type":"number","minimum":0,"maximum":4294967295,"description":"Text-to-speech only: a seed for deterministic output."},"voiceSettings":{"$ref":"#/components/schemas/DreamerAudioVoiceSettingsDto"},"pronunciationDictionaryIds":{"maxItems":3,"description":"Text-to-speech only: up to 3 pronunciation dictionary ids.","type":"array","items":{"type":"string"}},"resolution":{"type":"number","enum":[1024,2048],"default":1024,"description":"Material only. 1K is the web/mobile default; 2K is an explicit high-detail opt-in."},"repeatPerMeter":{"type":"number","minimum":0.1,"maximum":100,"default":1,"description":"Material only. Physical texture scale expressed as tile repeats per metre."},"splatScope":{"type":"string","enum":["environment"],"default":"environment","description":"Gaussian splat only. World Labs generation is environment-scoped; object splats are not supported."},"vaultVisibility":{"type":"string","enum":["public","private"],"description":"Where the generated asset lands in the Vault. Defaults to the creator's account preference (public unless they opted out). Pass `private` for throwaway output — a QA run, an acceptance check, an experiment — so it does not rank in other people's `search_assets` results. Private assets stay fully visible to their owner. Callers on a configured test account are forced private regardless of this field."},"projectId":{"type":"string"},"sessionId":{"type":"string"}},"required":["kind"]},"StartQuotedAssetGenerationRequestDto":{"type":"object","properties":{"quoteToken":{"type":"string","description":"The opaque, short-lived quote token returned by POST /api/v1/dreamer/assets/quotes.","maxLength":16384},"idempotencyKey":{"type":"string","description":"Stable key for the user action. Replaying the same quote always resolves to the same job.","minLength":8,"maxLength":96}},"required":["quoteToken","idempotencyKey"]},"PublishPricingConfigRequestDto":{"type":"object","properties":{"config":{"type":"object","description":"The complete pricing document (GenerationPricingConfig). Its `version` must be exactly one greater than the current highest version.","additionalProperties":true},"note":{"type":"string","description":"Why this price list exists. Stored with the version — a price change with no reason is unauditable six months later.","example":"Tripo raised Auto Rig to 30 credits; rigging repriced to match."}},"required":["config","note"]},"CreateProjectDto":{"type":"object","properties":{}},"UpdateProjectDto":{"type":"object","properties":{}},"CreateVersionDto":{"type":"object","properties":{}},"CreateAssetUploadUrlDto":{"type":"object","properties":{}},"RegisterAssetDto":{"type":"object","properties":{}},"UpdateVaultAssetRequestDto":{"type":"object","properties":{"title":{"type":"string","maxLength":150},"description":{"type":"object","maxLength":2000,"description":"Pass null to clear.","nullable":true},"tags":{"description":"REPLACES the tag set. Normalised, de-duplicated, capped at 20.","type":"array","items":{"type":"string"}},"contentRating":{"type":"string","enum":["everyone","teen","mature","adult"],"description":"Re-declare the rating. A correction is a NEW declaration: it re-enters review, so this cannot be used to quietly walk a rating back down."},"contentRatingAttestationAccepted":{"type":"boolean"}}},"SetVaultAssetOfficialRequestDto":{"type":"object","properties":{"official":{"type":"boolean","description":"TRUE marks the asset platform-official; FALSE clears it."}},"required":["official"]},"SpawnWorldItemRequestDto":{"type":"object","properties":{"worldId":{"type":"string","format":"uuid","description":"The world to spawn into. Either `worldId` or `worldSlug` is required."},"worldSlug":{"type":"string","description":"The world to spawn into, by slug. Alternative to `worldId`."},"transform":{"type":"object","description":"Engine-agnostic placement transform: `{ position: {x,y,z}, rotationEulerDeg?: {x,y,z}, scale?: number }`. Defaults to the world origin when omitted. Every number must be finite; position and scale are bounded server-side."}}},"WorldSpawnDto":{"type":"object","properties":{"placementId":{"type":"string","format":"uuid"},"instanceId":{"type":"string","format":"uuid","description":"The canonical instance id (`user_inventory_items.id`) that is standing here."},"itemId":{"type":"string","format":"uuid"},"worldId":{"type":"string","format":"uuid"},"ownerUserId":{"type":"string","format":"uuid"},"ownerUsername":{"type":"object","nullable":true,"description":"Null only when the owner row could not be loaded."},"kind":{"type":"string","example":"prop"},"usage":{"type":"string","example":"place"},"name":{"type":"string","example":"Neon Lounge Chair"},"thumbnailUrl":{"type":"object","nullable":true},"modelUrl":{"type":"object","nullable":true,"description":"The item's browser GLB (`web` rendition). Null when the item has no web build — the client should skip rendering rather than guess."},"transform":{"type":"object"},"state":{"type":"object","description":"The INSTANCE's per-unit state (`user_inventory_items.state`) — the canvas image bound to this poster, this serial's dye. It is the same fact in a backpack and in a world, so it is read live from the instance rather than snapshotted at spawn."},"spawnedAt":{"format":"date-time","type":"string"}},"required":["placementId","instanceId","itemId","worldId","ownerUserId","ownerUsername","kind","usage","name","thumbnailUrl","modelUrl","transform","state","spawnedAt"]},"WorldRecallResponseDto":{"type":"object","properties":{"recalled":{"type":"boolean","example":true}},"required":["recalled"]},"ItemEditApprovalTokenDto":{"type":"object","properties":{"sourceJobId":{"type":"string","format":"uuid"},"editOperationId":{"type":"string","maxLength":128},"gate":{"type":"string","enum":["concept","preview"]},"decision":{"type":"string","enum":["approve","decline"],"default":"approve"}},"required":["sourceJobId","editOperationId","gate","decision"]},"EditAdoptDto":{"type":"object","properties":{"kind":{"type":"string","enum":["world","item"],"description":"Assets are not adoptable: a Vault asset is a file, not a unit of creation, and its workspace is assembled from its generating job."},"id":{"type":"string","format":"uuid"}},"required":["kind","id"]},"WorldSourceUploadTicketDto":{"type":"object","properties":{"key":{"type":"string","description":"R2 object key the client must send back to finalize after uploading."},"url":{"type":"string","description":"Presigned PUT URL into the PRIVATE source bucket. ContentLength, ContentType and Cache-Control are bound into the signature."},"contentType":{"type":"string","description":"Content-Type the client must send on the PUT."},"cacheControl":{"type":"string","description":"Cache-Control the client must send on the PUT (part of the signature). Always 'no-store' — source is private."},"projectId":{"type":"string","description":"The project this world was adopted into. Source is keyed by project, and this is the same key edit mode resolves to."},"version":{"type":"string","description":"The version id this upload will be recorded as."},"expiresInSeconds":{"type":"number","description":"Seconds until the presigned URL expires."}},"required":["key","url","contentType","cacheControl","projectId","version","expiresInSeconds"]},"WorldSourceUploadRequestDto":{"type":"object","properties":{"contentType":{"type":"string","description":"MIME type of the archive. Only gzip tarballs are accepted (application/gzip, application/x-gzip).","example":"application/gzip"},"size":{"type":"number","description":"Exact byte size of the archive. Bound into the presigned PUT.","example":2411023}},"required":["contentType","size"]},"WorldSourceVersionDto":{"type":"object","properties":{"versionId":{"type":"string","description":"The project_versions row id."},"projectId":{"type":"string","description":"The project the version belongs to."},"key":{"type":"string","description":"R2 key of the stored source archive."},"version":{"type":"string","description":"Version id (the key segment)."},"sizeBytes":{"type":"number","description":"Verified byte size of the stored archive."},"createdAt":{"format":"date-time","type":"string","description":"When the version was recorded."}},"required":["versionId","projectId","key","version","sizeBytes","createdAt"]},"WorldSourceFinalizeRequestDto":{"type":"object","properties":{"key":{"type":"string","description":"The R2 key returned by the upload ticket.","example":"project-source/6f1c1b4e-0c5c-4a1e-8a1a-2f5b1a6a9a11/20260802T101530Z-a1b2c3d4.tar.gz"},"size":{"type":"number","description":"Exact byte size that was uploaded. Must equal the object stored in R2.","example":2411023}},"required":["key","size"]},"UpdatePhoneAppPermissionsDto":{"type":"object","properties":{}},"CreatePhoneReportDto":{"type":"object","properties":{"targetType":{"type":"string","description":"The kind of entity being reported.","enum":["post","user","comment","story","other"]},"targetId":{"type":"string","description":"Identifier of the reported entity within its source app.","maxLength":128},"appId":{"type":"string","description":"The phone app the report was filed from (e.g. \"helixgram\").","maxLength":64},"reason":{"type":"string","description":"Short machine/user-selected reason code or label.","maxLength":120},"details":{"type":"string","description":"Free-form details provided by the reporter."}},"required":["targetType","targetId","appId"]},"UpsertPhoneSocialDiscoveryProfileDto":{"type":"object","properties":{}},"RecordPhoneSocialDiscoverySwipeDto":{"type":"object","properties":{}},"PurchasePhoneIapDto":{"type":"object","properties":{}},"CreatePhoneNotificationDto":{"type":"object","properties":{}},"UploadPhoneAlbumAssetDto":{"type":"object","properties":{}},"SendPhoneMessageDto":{"type":"object","properties":{}},"ReactToPhoneMessageDto":{"type":"object","properties":{}},"PlacePhoneCallDto":{"type":"object","properties":{}},"UpdatePhoneCallStatusDto":{"type":"object","properties":{}},"UpsertPhoneAppStorageDto":{"type":"object","properties":{}},"TakeDownPhoneMediaDto":{"type":"object","properties":{}},"ModerationReportEvidenceDto":{"type":"object","properties":{"kind":{"type":"string","enum":["screenshot","image","video","audio","chat_log","url","file","metadata"],"description":"Evidence metadata kind. Files are not uploaded here in V1."},"label":{"type":"string","description":"Short moderator-visible label."},"url":{"type":"string","description":"Existing asset, screenshot, or clip URL."},"mimeType":{"type":"string","example":"image/png","description":"Required for attachment kinds (screenshot/image/video/file) and must be an image or video type. Optional for url/chat_log/audio/metadata."},"storageKey":{"type":"string","description":"Storage key returned by POST /moderation/reports/evidence-uploads after the file was PUT to its presigned URL (HYPR-5216). The server verifies ownership, size, and actual content before binding it."},"sizeBytes":{"type":"number","description":"Evidence byte size, if known."},"sha256":{"type":"string","description":"SHA-256 checksum, if available."},"capturedAt":{"type":"string","description":"ISO timestamp when evidence was captured."},"metadata":{"type":"object","description":"Additional structured evidence metadata."}}},"CreateModerationReportDto":{"type":"object","properties":{"targetType":{"type":"string","enum":["user","world","home","universal_item","canvas_item","collectible","collectible_instance","helixgram_post","helixgram_comment","helixgram_story","h_post","phone_post","phone_comment","phone_story","other"],"description":"Universal target type being reported."},"targetId":{"type":"string","description":"Target id. UUID for first-party HELIX objects."},"targetLabel":{"type":"string","description":"Readable label captured at report time."},"reportedUserId":{"type":"string","description":"Reported/owning user id when the backend cannot infer it, such as canvas_item or other."},"type":{"type":"string","description":"Report type/reason such as harassment, sexual_content, spam."},"details":{"type":"string","description":"Moderator-facing details."},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"evidence":{"description":"Evidence attachment metadata; V1 does not upload files here.","type":"array","items":{"$ref":"#/components/schemas/ModerationReportEvidenceDto"}},"metadata":{"type":"object","description":"Client context such as route or instance."}},"required":["targetType","targetId","type"]},"ReportEvidenceUploadFileDto":{"type":"object","properties":{"mimeType":{"type":"string","example":"image/png","description":"Declared type — the bytes are re-checked at submission."},"sizeBytes":{"type":"number","description":"Declared byte size of the file."},"filename":{"type":"string","description":"Original filename, informational only — storage keys are server-owned."}},"required":["mimeType","sizeBytes"]},"ReportEvidenceUploadRequestDto":{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/ReportEvidenceUploadFileDto"}}},"required":["files"]},"UpdateModerationReportDto":{"type":"object","properties":{"status":{"type":"string","enum":["open","reviewing","resolved","dismissed","actioned"]},"action":{"type":"string","description":"Admin action label, if action was taken."},"moderatorNote":{"type":"string","description":"Private moderator note."},"takedown":{"type":"boolean","description":"Take the reported content down as part of resolving this report (HYPR-5215). Items are Delisted, worlds Suspended — both admin-reversible. Without this the report is only annotated: `action` is a free-text label and changes nothing about the content."}}},"UpdateContentRatingDto":{"type":"object","properties":{"targetType":{"type":"string","enum":["world","home","universal_item"]},"targetId":{"type":"string","description":"World, home, or universal item id."},"rating":{"type":"string","enum":["general","teen","mature","adult"]},"status":{"type":"string","enum":["pending_review","approved","flagged","rejected"]},"note":{"type":"string","description":"Private reason for the rating decision."},"metadata":{"type":"object","description":"Structured admin/rating-worker metadata."}},"required":["targetType","targetId","rating","status"]},"SuspendCreationDto":{"type":"object","properties":{"reason":{"type":"string","description":"Why publishing is being paused for this account. Recorded on the user row and in the moderation ledger; internal, never shown to the creator (they see the standing message instead).","example":"4 automated rejections in 90d, manual confirmation.","maxLength":2000}},"required":["reason"]},"UnsuspendCreationDto":{"type":"object","properties":{"note":{"type":"string","description":"Optional note recorded on the ledger row for the lift.","maxLength":2000}}},"ModerationSurfaceSettingDto":{"type":"object","properties":{"mode":{"type":"string","enum":["enforce","monitor","off"]},"reason":{"type":"string","description":"Why this surface is not enforcing. Required for anything but `enforce`."},"expiresAt":{"type":"string","description":"When this setting auto-reverts, ISO-8601. Defaults to 24h from now when omitted on a non-enforce setting."}},"required":["mode"]},"UpdateModerationPolicyDto":{"type":"object","properties":{"global":{"$ref":"#/components/schemas/ModerationSurfaceSettingDto"},"surfaces":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ModerationSurfaceSettingDto"}},"reason":{"type":"string","description":"Why this change is being made. Required."}},"required":["global","reason"]},"RevertModerationPolicyDto":{"type":"object","properties":{"reason":{"type":"string","description":"Why the previous posture is being restored."}},"required":["reason"]},"CreateModerationOverrideDto":{"type":"object","properties":{"reason":{"type":"string","description":"Why these bytes were judged publishable despite the provider flagging them. Recorded permanently and shown in the override audit list, so write it for a reviewer who was not present — e.g. \"Flat brown leather texture for a sofa; Rekognition mis-scored the skin-tone gradient as nudity at 90.7%. Reviewed the image: no human figure present.\"","minLength":10,"maxLength":2000}},"required":["reason"]},"RevokeModerationOverrideDto":{"type":"object","properties":{"reason":{"type":"string","description":"Why the override is being retired. Optional — revoking restores the strict default, so it never needs justifying the way granting one does.","maxLength":2000}}},"HPostAttachmentDto":{"type":"object","properties":{"assetId":{"type":"string","description":"Id of the phone album asset to attach to this H post."}},"required":["assetId"]},"CreateHPostDto":{"type":"object","properties":{"body":{"type":"string","maxLength":280,"minLength":1},"attachments":{"description":"Up to 4 phone album assets (photos/videos) to attach to the post.","type":"array","items":{"$ref":"#/components/schemas/HPostAttachmentDto"}}},"required":["body"]},"CreateHReplyDto":{"type":"object","properties":{"body":{"type":"string","maxLength":280,"minLength":1},"attachments":{"description":"Up to 4 phone album assets (photos/videos) to attach to the post.","type":"array","items":{"$ref":"#/components/schemas/HPostAttachmentDto"}}},"required":["body"]},"CreateHReportDto":{"type":"object","properties":{}},"CreatorAnalyticsRangeDto":{"type":"object","properties":{"from":{"type":"string","example":"2026-07-06T00:00:00.000Z"},"to":{"type":"string","example":"2026-08-02T00:00:00.000Z"},"grain":{"type":"string","example":"day","enum":["day","week","month"]}},"required":["from","to","grain"]},"CreatorAnalyticsBreakdownRowDto":{"type":"object","properties":{"subjectType":{"type":"string","enum":["world","item"]},"id":{"type":"string"},"title":{"type":"string"},"thumbnailUrl":{"type":"string","nullable":true},"grossLix":{"type":"string","example":"3120.0000"},"units":{"type":"number"},"buyers":{"type":"number"},"lastSaleAt":{"type":"string","nullable":true},"visits":{"type":"number","nullable":true,"description":"world_entered events in the window. null for ITEM rows (a world visit is not an item concept) and null beyond 90 days, where the raw-event store cannot answer — see unavailable[]. NEVER 0 for \"we did not measure\"."},"previousVisits":{"type":"number","nullable":true,"description":"Same, previous window — so the worlds table can carry a delta arrow on visits. null when compare=none."}},"required":["subjectType","id","title","thumbnailUrl","grossLix","units","buyers","lastSaleAt","visits","previousVisits"]},"CreatorAnalyticsTopBuyerDto":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true},"grossLix":{"type":"string","example":"640.0000"},"units":{"type":"number"},"firstPurchaseAt":{"type":"string"},"lastPurchaseAt":{"type":"string"}},"required":["id","username","avatarUrl","grossLix","units","firstPurchaseAt","lastPurchaseAt"]},"CreatorAnalyticsLifetimeDto":{"type":"object","properties":{"grossLix":{"type":"string","example":"48210.0000"},"firstSaleAt":{"type":"string","nullable":true,"example":"2026-03-03"}},"required":["grossLix","firstSaleAt"]},"CreatorAnalyticsCameBackDto":{"type":"object","properties":{"rate":{"type":"number","nullable":true,"example":0.14},"cohortSize":{"type":"number","example":100},"returnedActors":{"type":"number","example":14},"cohortFrom":{"type":"string","example":"2026-07-13"},"cohortTo":{"type":"string","example":"2026-07-20"},"cohortScope":{"type":"string","enum":["signed_in","all"],"example":"signed_in"}},"required":["rate","cohortSize","returnedActors","cohortFrom","cohortTo","cohortScope"]},"CreatorAnalyticsCapsDto":{"type":"object","properties":{"breakdownLimit":{"type":"number"},"topBuyersLimit":{"type":"number"},"breakdownTruncated":{"type":"boolean"},"visitsTruncated":{"type":"boolean","description":"Always false on this endpoint: earnings are SQL aggregates over the money ledgers, not the 5,000-row raw-event scan."}},"required":["breakdownLimit","topBuyersLimit","breakdownTruncated","visitsTruncated"]},"CreatorAnalyticsSummaryResponseDto":{"type":"object","properties":{"asOf":{"type":"string"},"sealedThrough":{"type":"string","nullable":true,"description":"Latest UTC day fully recomputed from authoritative sources. null before the first seal."},"partialDay":{"type":"boolean","description":"True when the requested window includes data later than sealedThrough."},"range":{"$ref":"#/components/schemas/CreatorAnalyticsRangeDto"},"previousRange":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorAnalyticsRangeDto"}]},"revenueBasis":{"type":"string","example":"gross","enum":["gross"],"description":"Literal, always."},"currency":{"type":"string","example":"LIX"},"totals":{"$ref":"#/components/schemas/CreatorAnalyticsTotalsDto"},"previous":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorAnalyticsTotalsDto"}]},"trend":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsTrendPointDto"}},"previousTrend":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsTrendPointDto"}},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsBreakdownRowDto"}},"topBuyers":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsTopBuyerDto"}},"referrers":{"type":"array","items":{"type":"object"},"description":"Empty + listed in unavailable[] — the referrer lens belongs to the analytics engine."},"issues":{"type":"object","additionalProperties":{"type":"number"},"nullable":true,"description":"null = not measured by this lane. Never a zeroed object."},"lifetime":{"$ref":"#/components/schemas/CreatorAnalyticsLifetimeDto"},"cohortScope":{"type":"string","enum":["signed_in","all"],"example":"signed_in"},"cameBack7d":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorAnalyticsCameBackDto"}]},"caps":{"$ref":"#/components/schemas/CreatorAnalyticsCapsDto"},"unavailable":{"example":["netEarnings","playtime","revenueByReferrer"],"description":"A key here renders \"not measured\", NEVER a zero.","type":"array","items":{"type":"string"}}},"required":["asOf","sealedThrough","partialDay","range","previousRange","revenueBasis","currency","totals","previous","trend","previousTrend","breakdown","topBuyers","referrers","issues","lifetime","cohortScope","cameBack7d","caps","unavailable"]},"CreatorAnalyticsItemPortfolioTotalsDto":{"type":"object","properties":{"grossLix":{"type":"string","example":"3720.5000"},"units":{"type":"number","example":124},"views":{"type":"number","nullable":true},"conversion":{"type":"number","nullable":true}},"required":["grossLix","units","views","conversion"]},"CreatorAnalyticsSubjectRowDto":{"type":"object","properties":{"subjectType":{"type":"string","enum":["world","item"]},"id":{"type":"string"},"title":{"type":"string"},"thumbnailUrl":{"type":"string","nullable":true},"grossLix":{"type":"string","example":"3120.0000"},"units":{"type":"number"},"buyers":{"type":"number"},"lastSaleAt":{"type":"string","nullable":true},"visits":{"type":"number","nullable":true,"description":"world_entered events in the window. null for ITEM rows (a world visit is not an item concept) and null beyond 90 days, where the raw-event store cannot answer — see unavailable[]. NEVER 0 for \"we did not measure\"."},"previousVisits":{"type":"number","nullable":true,"description":"Same, previous window — so the worlds table can carry a delta arrow on visits. null when compare=none."},"status":{"type":"string","enum":["draft","published","delisted","suspended","hidden","rejected","archived"],"nullable":true},"kind":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"isCollectible":{"type":"boolean","nullable":true},"collectibleId":{"type":"string","format":"uuid","nullable":true},"views":{"type":"number","nullable":true,"description":"null when the view engine is unbound."},"conversion":{"type":"number","nullable":true,"description":"units / views. null when views are unknown OR zero — never 0."},"checklist":{"type":"array","nullable":true,"description":"Tier-0 codes for item rows. [] means checked and nothing fires; null is reserved for non-item rows.","items":{"type":"string","enum":["no_preview_asset","no_thumbnail","no_tags","price_outside_band","not_placed_in_own_world","draft_stale"]}},"sparkline":{"description":"14-point gross sparkline over the range.","type":"array","items":{"type":"number"}}},"required":["subjectType","id","title","thumbnailUrl","grossLix","units","buyers","lastSaleAt","visits","previousVisits","status","kind","category","isCollectible","collectibleId","views","conversion","checklist","sparkline"]},"CreatorAnalyticsSubjectsResponseDto":{"type":"object","properties":{"revenueBasis":{"type":"string","example":"gross","enum":["gross"]},"range":{"$ref":"#/components/schemas/CreatorAnalyticsRangeDto"},"totals":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorAnalyticsItemPortfolioTotalsDto"}]},"previous":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorAnalyticsItemPortfolioTotalsDto"}]},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsSubjectRowDto"}},"nextCursor":{"type":"string","nullable":true},"unavailable":{"type":"array","items":{"type":"string"}}},"required":["revenueBasis","range","totals","previous","items","nextCursor","unavailable"]},"CreatorAnalyticsChecklistItemDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"checklist":{"type":"array","description":"Stable Tier-0 codes in deterministic action order. [] means every rule was evaluated and none fired.","items":{"type":"string","enum":["no_preview_asset","no_thumbnail","no_tags","price_outside_band","not_placed_in_own_world","draft_stale"]}}},"required":["id","checklist"]},"CreatorAnalyticsChecklistResponseDto":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsChecklistItemDto"}}},"required":["items"]},"CreatorAnalyticsSubjectIdentityDto":{"type":"object","properties":{"subjectType":{"type":"string","enum":["world","item"]},"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"thumbnailUrl":{"type":"string","nullable":true},"status":{"type":"string","enum":["draft","published","delisted","suspended","hidden","rejected","archived"],"nullable":true}},"required":["subjectType","id","title","thumbnailUrl","status"]},"CreatorAnalyticsSoldWhereDto":{"type":"object","properties":{"bucket":{"type":"string","example":"world:8e58d6f0-0000-4000-8000-000000000000","description":"Derived from ref_type, NEVER from worldId === null: \"marketplace\" | \"world:<uuid>\" | \"world:deleted\"."},"worldId":{"type":"string","nullable":true},"title":{"type":"string"},"units":{"type":"number"},"grossLix":{"type":"string"},"buyers":{"type":"number"}},"required":["bucket","worldId","title","units","grossLix","buyers"]},"CreatorAnalyticsCollectibleSubjectDto":{"type":"object","properties":{"secondaryVolumeLix":{"type":"string","example":"2200.0000"},"lastSalePriceLix":{"type":"string","nullable":true,"example":"310.0000"},"allTimeHighPriceLix":{"type":"string","example":"420.0000"},"lastSaleAt":{"type":"string","nullable":true},"ownershipHistoryHref":{"type":"string","example":"/items/uuid#item-instances"}},"required":["secondaryVolumeLix","lastSalePriceLix","allTimeHighPriceLix","lastSaleAt","ownershipHistoryHref"]},"CreatorAnalyticsItemSubjectDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string"},"category":{"type":"string"},"isCollectible":{"type":"boolean"},"collectibleId":{"type":"string","format":"uuid","nullable":true},"checklist":{"type":"array","items":{"type":"string","enum":["no_preview_asset","no_thumbnail","no_tags","price_outside_band","not_placed_in_own_world","draft_stale"]}},"collectible":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorAnalyticsCollectibleSubjectDto"}]}},"required":["id","kind","category","isCollectible","collectibleId","checklist","collectible"]},"CreatorAnalyticsSubjectResponseDto":{"type":"object","properties":{"asOf":{"type":"string"},"sealedThrough":{"type":"string","nullable":true,"description":"Latest UTC day fully recomputed from authoritative sources. null before the first seal."},"partialDay":{"type":"boolean","description":"True when the requested window includes data later than sealedThrough."},"range":{"$ref":"#/components/schemas/CreatorAnalyticsRangeDto"},"previousRange":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorAnalyticsRangeDto"}]},"revenueBasis":{"type":"string","example":"gross","enum":["gross"],"description":"Literal, always."},"currency":{"type":"string","example":"LIX"},"totals":{"$ref":"#/components/schemas/CreatorAnalyticsTotalsDto"},"previous":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorAnalyticsTotalsDto"}]},"trend":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsTrendPointDto"}},"previousTrend":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsTrendPointDto"}},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsBreakdownRowDto"}},"topBuyers":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsTopBuyerDto"}},"referrers":{"type":"array","items":{"type":"object"},"description":"Empty + listed in unavailable[] — the referrer lens belongs to the analytics engine."},"issues":{"type":"object","additionalProperties":{"type":"number"},"nullable":true,"description":"null = not measured by this lane. Never a zeroed object."},"lifetime":{"$ref":"#/components/schemas/CreatorAnalyticsLifetimeDto"},"cohortScope":{"type":"string","enum":["signed_in","all"],"example":"signed_in"},"cameBack7d":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorAnalyticsCameBackDto"}]},"caps":{"$ref":"#/components/schemas/CreatorAnalyticsCapsDto"},"unavailable":{"example":["netEarnings","playtime","revenueByReferrer"],"description":"A key here renders \"not measured\", NEVER a zero.","type":"array","items":{"type":"string"}},"subject":{"$ref":"#/components/schemas/CreatorAnalyticsSubjectIdentityDto"},"soldWhere":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsSoldWhereDto"}},"item":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/CreatorAnalyticsItemSubjectDto"}]}},"required":["asOf","sealedThrough","partialDay","range","previousRange","revenueBasis","currency","totals","previous","trend","previousTrend","breakdown","topBuyers","referrers","issues","lifetime","cohortScope","cameBack7d","caps","unavailable","subject","soldWhere","item"]},"CreatorAnalyticsCustomerProductDto":{"type":"object","properties":{"subjectType":{"type":"string","enum":["item","product"]},"id":{"type":"string"},"title":{"type":"string"},"marketplaceHref":{"type":"string","nullable":true},"grossLix":{"type":"string","example":"640.0000"},"units":{"type":"number"}},"required":["subjectType","id","title","marketplaceHref","grossLix","units"]},"CreatorAnalyticsCustomerResponseDto":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true},"grossLix":{"type":"string","example":"640.0000"},"units":{"type":"number"},"firstPurchaseAt":{"type":"string"},"lastPurchaseAt":{"type":"string"},"topProducts":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalyticsCustomerProductDto"}}},"required":["id","username","avatarUrl","grossLix","units","firstPurchaseAt","lastPurchaseAt","topProducts"]},"FtueStepResponseDto":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"objective":{"type":"string"},"description":{"type":"string"},"target":{"type":"string"},"routeHint":{"type":"string"},"completed":{"type":"boolean"},"reward":{"type":"object"}},"required":["id","title","objective","target","routeHint","completed"]},"FtueEntryResponseDto":{"type":"object","properties":{"usernameRequired":{"type":"boolean"},"interestsDone":{"type":"boolean"},"avatarDone":{"type":"boolean"},"completedAt":{"type":"object","nullable":true}},"required":["usernameRequired","interestsDone","avatarDone","completedAt"]},"FtueStateResponseDto":{"type":"object","properties":{"status":{"type":"string","enum":["not_started","active","completed","abandoned"]},"entryContext":{"type":"string","enum":["generic","invite","world","home","item","profile"]},"currentStepId":{"type":"string"},"completedSteps":{"type":"array","items":{"type":"string"}},"destinationUrl":{"type":"object"},"destinationWorldId":{"type":"object"},"destinationHomeId":{"type":"object"},"destinationItemId":{"type":"object"},"destinationProfileUserId":{"type":"object"},"inviteId":{"type":"object"},"inviterUserId":{"type":"object"},"interests":{"type":"array","items":{"type":"string"}},"steps":{"type":"array","items":{"$ref":"#/components/schemas/FtueStepResponseDto"}},"entry":{"$ref":"#/components/schemas/FtueEntryResponseDto"},"dismissedHud":{"type":"boolean"},"selectedAvatarId":{"type":"object","nullable":true},"defaultHomeId":{"type":"object"},"defaultHomeSlug":{"type":"object"},"recommendedWorldId":{"type":"object"},"recommendedWorldSlug":{"type":"object"},"inviteCode":{"type":"object"},"startedAt":{"type":"object"},"completedAt":{"type":"object"},"lastSeenAt":{"type":"object"}},"required":["status","entryContext","currentStepId","completedSteps","interests","steps","entry","dismissedHud","selectedAvatarId"]},"StartFtueRequestDto":{"type":"object","properties":{"entryContext":{"type":"string","enum":["generic","invite","world","home","item","profile"]},"destinationUrl":{"type":"string"},"destinationWorldId":{"type":"string"},"destinationHomeId":{"type":"string"},"destinationItemId":{"type":"string"},"destinationProfileUserId":{"type":"string"},"inviteId":{"type":"string"},"inviterUserId":{"type":"string"},"metadata":{"type":"object"}}},"UpdateFtueInterestsRequestDto":{"type":"object","properties":{"interests":{"type":"array","items":{"type":"string","enum":["fps","battle_royale","life_sim","competitive","cozy","create","fashion","racing","hangout","arcade","roleplay","horror","sports","strategy","survival"]}}},"required":["interests"]},"UpdateFtueAvatarRequestDto":{"type":"object","properties":{"avatarId":{"type":"object","nullable":true}}},"CompleteFtueStepRequestDto":{"type":"object","properties":{"metadata":{"type":"object"}}},"ClaimStarterRewardsRequestDto":{"type":"object","properties":{"sessionId":{"type":"string","description":"Optional frontend session id used for analytics correlation."},"source":{"type":"string","description":"Optional source label for the reward claim.","example":"web-ftue-orchestrator"},"metadata":{"type":"object"}}},"ProvisionTestAccountsRequestDto":{"type":"object","properties":{"count":{"type":"number","description":"Number of stable multiplayer QA fixtures to ensure.","minimum":1,"maximum":10,"example":2}},"required":["count"]},"QaTestAccountDto":{"type":"object","properties":{"id":{"type":"string","example":"c4f5f49b-b565-4c4a-b89e-56fc5ab6b35d"},"label":{"type":"string","example":"kostas+mp1"},"email":{"type":"string","example":"kostas+mp1@hypersoniclabs.co"},"username":{"type":"string","example":"kostas-mp1"},"isTestAccount":{"type":"boolean","example":true},"qaFixture":{"type":"boolean","example":true},"verifiedAt":{"type":"string","example":"2026-08-17T10:00:00.000Z"},"created":{"type":"boolean","description":"True only when this request inserted the row.","example":false}},"required":["id","label","email","username","isTestAccount","qaFixture","verifiedAt","created"]},"ProvisionTestAccountsResponseDto":{"type":"object","properties":{"accounts":{"type":"array","items":{"$ref":"#/components/schemas/QaTestAccountDto"}}},"required":["accounts"]},"MissionControlActionDto":{"type":"object","properties":{}}}}}