diff --git a/docs/glossary.md b/docs/glossary.md index acb96eb..fd9b9f1 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -211,3 +211,35 @@ Endpoints that accept a matchmaking type should also accept a string in its plac ### Zone ID UUID that identifies a zone. The full list of zones (including their hierarchical structure) is available via the [Core API's zones endpoint](/core/meta/zones). + +### Club privacy levels + +Privacy levels for new members that can be set when creating / editing a club. These include: + +* `"public"`: Public - Open to everyone. Allows everyone to join the club directly. +* `"private-open"`: Private - Accept requests. Players can request to join the club in-game. Requests need to be approved by a moderator. +* `"private-closed"`: Private. The club does not accept new members. The club will still be visible in-game. + +### Room regions + +Server regions where a room can be hosted. This can be set when creating / editing a club room. Regions include: + +* `"eu-west"`: EU West. +* `"ca-central"`: Canada Central. +* `"ap-southeast"`: Asia Pacific. + +### Club upload activity types + +Activity types supported for assets when creating a club upload activity. These include: + +* `"map-upload"`: Track uploads. +* `"skin-upload"`: Skin uploads. +* `"item-upload"`: Item collections. A group of items that players can add to their map editor in-game. + +Item collections need to be compressed as a .zip file and placed in the `ItemCollections` folder in the Trackmania Documents folder. + +### Club folders + +Folders in clubs that can be used to organize activities. Nested folders are supported. + +If the folder ID of an activity is set to `0`, the activity will be moved outside the folder. Similarly, deleting a folder will move the activities outside it. diff --git a/docs/live/club-management/add-to-upload.md b/docs/live/club-management/add-to-upload.md new file mode 100644 index 0000000..13512ae --- /dev/null +++ b/docs/live/club-management/add-to-upload.md @@ -0,0 +1,91 @@ +--- +name: Add items to club upload activity + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/bucket/{bucketId}/add + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the upload activity belongs to + required: true + - name: bucketId + type: integer + description: The ID of the upload activity where the items should be added + required: true + body: + - name: itemIdList + type: string[] + description: A list of items to add to the upload activity, identified by their ID (see remarks below) + required: true +--- + +The request body is an object containing the items to be added: + +```json +{ + "itemIdList": itemIdList +} +``` + +Adds a list of maps, items, or skins to an upload activity in a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- The IDs needed for the `itemIdList` parameter depend on the type of upload activity requested. For maps uploads, it requires their `mapUid`, while skins and items require their `skinID` and `itemID`, respectively. +- When passing an invalid ID, including IDs for other upload types, the items will be added, but an error might be displayed in-game when accessing the activity. +- Assets used for this endpoint must be uploaded to Nadeo's servers beforehand. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/103034/bucket/1009342/add +``` + +```json +{ + "itemIdList": [ + "KRelvYHRjEQoqnkJ_Th8FLKzTsg", + "3LRPuWYIe85IJBbUcmIHkaSBuHh" + ] +} +``` + +**Example response**: + +```plain +Items added. +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the upload activity does not exist, the response will contain an error: + +```json +[ + "activity:error-notFound" +] +``` + +If the authenticated account does not have enough permissions in the club to edit upload activities, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` diff --git a/docs/live/club-management/create-campaign.md b/docs/live/club-management/create-campaign.md new file mode 100644 index 0000000..032eb1b --- /dev/null +++ b/docs/live/club-management/create-campaign.md @@ -0,0 +1,196 @@ +--- +name: Create club campaign + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/campaign/create + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club where the campaign should be created + required: true + body: + - name: name + type: string + description: The name of the new campaign + max: 20 characters + required: true + - name: playlist + type: object[] + description: A list of maps, with their positions and UIDs + children: + - name: position + type: integer + description: The position of the map in the campaign (see remarks below) + - name: mapUid + type: string + description: The UID of a specific map + - name: folderId + type: integer + description: The ID of the folder where the campaign should be created +--- + +The request body is an object containing the campaign details: + +```json +{ + "name": name, + "playlist": [ + { + "position": position, + "mapUid": mapUid + } + ], + "folderId": folderId +} +``` + +Creates a campaign in a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- Campaigns created using this endpoint will be deactivated by default. To activate them, use the [Edit activity Live endpoint](/live/club-management/edit-activity.md). +- The position of the maps in the campaign seems to be determined by their order in the `playlist` array in the request body, rather than by their `position` parameter. It is still recommended to pass the desired position. +- If a map is missing its `mapUid` or `position`, the campaign will be created, but the map will be skipped. +- Maps used for this endpoint must be uploaded to Nadeo's servers beforehand. +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. +- See the [glossary](/glossary#club-folders) for more information about folders. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/103034/campaign/create +``` + +```json +{ + "name": "RPG", + "playlist": [ + { + "position": 0, + "mapUid": "zx45UUBTayedFisP7N_wYWZa3Ih" + }, + { + "position": 1, + "mapUid": "XiynRhPNCztF7UeXGa7bmYL32xm" + } + ], + "folderId": 0 +} +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1771654457, + "clubName": "Fort's club", + "id": 1004334, + "clubDecalUrl": "", + "publicationTimestamp": 1771654457, + "activityId": 1004334, + "campaignId": 127119, + "name": "RPG", + "clubId": 103034, + "mediaUrlPngSmall": "", + "mediaUrl": "", + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "mediaUrlPngLarge": "", + "campaign": { + "day": -1, + "id": 127119, + "video": false, + "publicationTimestamp": 1771654457, + "monthDay": -1, + "color": "", + "name": "RPG", + "clubId": 103034, + "month": -1, + "endTimestamp": 0, + "monthYear": -1, + "rankingSentTimestamp": null, + "mediaUrl": "", + "startTimestamp": 1771654457, + "editionTimestamp": 1771654457, + "leaderboardGroupUid": "NLS-jZ46Fn4oNK9KLokxwvMLMo0bOwQFca1Dq0A", + "seasonUid": "NLS-jZ46Fn4oNK9KLokxwvMLMo0bOwQFca1Dq0A", + "categories": [ + { + "name": "RPG", + "position": 0, + "length": 5 + } + ], + "year": -1, + "media": { + "decalUrl": "", + "popUpImageUrl": "", + "liveButtonForegroundUrl": "", + "liveButtonBackgroundUrl": "", + "buttonBackgroundUrl": "", + "popUpBackgroundUrl": "", + "buttonForegroundUrl": "" + }, + "published": true, + "useCase": 2, + "playlist": [ + { + "id": 1516902, + "mapUid": "zx45UUBTayedFisP7N_wYWZa3Ih", + "position": 0 + }, + { + "id": 1516903, + "mapUid": "XiynRhPNCztF7UeXGa7bmYL32xm", + "position": 1 + } + ], + "week": -1, + "latestSeasons": [ + { + "uid": "NLS-jZ46Fn4oNK9KLokxwvMLMo0bOwQFca1Dq0A", + "campaignId": 127119, + "name": "RPG", + "endTimestamp": 0, + "startTimestamp": 1771654457, + "relativeEnd": 0, + "active": true, + "relativeStart": 0 + } + ] + }, + "mediaTheme": "", + "popularityLevel": 0, + "creatorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "mediaUrlDds": "", + "mapsCount": 2, + "mediaUrlPngMedium": "" +} +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the authenticated account does not have enough permissions in the club to create campaigns, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` + +An invalid or duplicated `mapUid` results in a `500` response code with an error object in the response body. diff --git a/docs/live/club-management/create-club.md b/docs/live/club-management/create-club.md new file mode 100644 index 0000000..732fbef --- /dev/null +++ b/docs/live/club-management/create-club.md @@ -0,0 +1,188 @@ +--- +name: Create club + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/create + +audience: NadeoLiveServices + +parameters: + body: + - name: name + type: string + description: The name of the new club + min: 3 characters + max: 20 characters + required: true + - name: state + type: string + description: The privacy level of the club (see remarks below) + required: true + - name: tag + type: string + description: The club tag for players to use in-game + max: 5 characters + - name: description + type: string + description: A description of the club + max: 200 characters + - name: iconTheme + type: string + description: The name of the theme preset for the icon displayed in the list of clubs in-game, in lower case + - name: decalTheme + type: string + description: The name of the theme preset for the image displayed at the start, checkpoints, and finishes, in lower case + - name: verticalTheme + type: string + description: The name of the theme preset for the vertical image displayed in My Clubs list, in lower case + - name: backgroundTheme + type: string + description: The name of the theme preset for the background displayed in the club details page, in lower case + - name: screen8x1Theme + type: string + description: The name of the theme preset for the image displayed on the stadium's bleachers, in lower case + - name: screen16x1Theme + type: string + description: The name of the theme preset for the image displayed on the stadium's banners below the big screen, in lower case + - name: screen16x9Theme + type: string + description: The name of the theme preset for the image displayed on the stadium's big screen, in lower case +--- + +The request body is an object containing the club details: + +```json +{ + "name": name, + "state": state, + "tag": tag, + "description": description, + "iconTheme": iconTheme, + "decalTheme": decalTheme, + "verticalTheme": verticalTheme, + "backgroundTheme": backgroundTheme, + "screen8x1Theme": screen8x1Theme, + "screen16x1Theme": screen16x1Theme, + "screen16x9Theme": screen16x9Theme +} +``` + +Creates a new club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- See the [glossary](/glossary#club-privacy-levels) for a list of available privacy levels. +- A list of theme presets that can be used for the theme parameters can be found in the following directory when selecting an image for a club activity: `Manialinks\Nadeo\CMGame\OfficialThemes`. +- The `tag` field supports text styling, which does not count towards the maximum character length. See the [Text Styling documentation](https://wiki.trackmania.io/en/content-creation/text-styling) for more information about the supported styles and syntax. +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/create +``` + +```json +{ + "name": "Testing club", + "state": "private-closed", + "tag": "DOCS", + "description": "This is a club for testing", + "iconTheme": "racing", + "decalTheme": "racing", + "verticalTheme": "valhalla", + "backgroundTheme": "valhalla", + "screen8x1Theme": "mirage", + "screen16x1Theme": "mirage", + "screen16x9Theme": "mirage" +} +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1771820094, + "walletUid": "559cd73b-de9d-45df-82b6-b36ae04bd668", + "id": 131063, + "decalUrl": "", + "decalSponsor4x1UrlPngLarge": "", + "backgroundUrlJpgLarge": "", + "decalSponsor4x1UrlDds": "", + "decalTheme": "racing", + "screen16x1Url": "", + "name": "Testing club", + "screen64x41Theme": "mirage", + "screen64x41UrlDds": "", + "featured": false, + "decalUrlPngMedium": "", + "screen64x41UrlPngLarge": "", + "screen16x1UrlDds": "", + "verified": false, + "screen16x9Theme": "mirage", + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "iconUrlPngMedium": "", + "backgroundUrlDds": "", + "editionTimestamp": 1771820094, + "backgroundUrlJpgSmall": "", + "tag": "DOCS", + "backgroundUrlJpgMedium": "", + "verticalUrlPngMedium": "", + "metadata": "", + "decalUrlPngSmall": "", + "verticalTheme": "valhalla", + "backgroundTheme": "valhalla", + "verticalUrlPngSmall": "", + "iconUrlPngSmall": "", + "iconUrl": "", + "popularityLevel": 0, + "screen8x1UrlDds": "", + "verticalUrlPngLarge": "", + "screen16x9Url": "", + "screen64x41UrlPngMedium": "", + "screen16x1UrlPngMedium": "", + "screen8x1UrlPngSmall": "", + "authorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "screen16x1UrlPngLarge": "", + "state": "private-closed", + "screen16x9UrlDds": "", + "verticalUrlDds": "", + "logoUrl": "", + "screen8x1UrlPngMedium": "", + "screen16x9UrlPngLarge": "", + "screen64x41Url": "", + "screen16x9UrlPngSmall": "", + "screen16x9UrlPngMedium": "", + "description": "This is a club for testing", + "decalSponsor4x1UrlPngSmall": "", + "screen8x1Theme": "mirage", + "screen8x1UrlPngLarge": "", + "verticalUrl": "", + "screen16x1Theme": "mirage", + "iconTheme": "racing", + "screen64x41UrlPngSmall": "", + "decalUrlPngLarge": "", + "iconUrlPngLarge": "", + "decalUrlDds": "", + "decalSponsor4x1Url": "", + "screen8x1Url": "", + "iconUrlDds": "", + "screen16x1UrlPngSmall": "", + "decalSponsor4x1UrlPngMedium": "", + "backgroundUrl": "" +} +``` + +If the `state` parameter is invalid, the response will contain an error: + +```json +[ + "state:error-inArray" +] +``` diff --git a/docs/live/club-management/create-folder.md b/docs/live/club-management/create-folder.md new file mode 100644 index 0000000..25f9cef --- /dev/null +++ b/docs/live/club-management/create-folder.md @@ -0,0 +1,105 @@ +--- +name: Create club folder + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/folder/create + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club where the folder should be created + required: true + body: + - name: name + type: string + description: The name of the new folder + required: true + - name: folderId + type: integer + description: The ID of the parent folder +--- + +The request body is an object containing the name of the club folder and its parent folder's ID: + +```json +{ + "name": name, + "folderId": folderId, +} +``` + +Creates a folder in a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. +- See the [glossary](/glossary#club-folders) for more information about folders. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/103034/folder/create +``` + +```json +{ + "name": "My maps", + "folderId": 0 +} +``` + +**Example response**: + +```json +{ + "id": 1004355, + "folderId": null, + "public": true, + "activityId": 1004355, + "campaignId": 0, + "name": "My maps", + "clubId": 103034, + "password": false, + "featured": false, + "activityType": "folder", + "mediaUrlPngSmall": "", + "mediaUrl": "", + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "editionTimestamp": 1771658680, + "mediaUrlPngLarge": "", + "itemsCount": 0, + "mediaTheme": "", + "position": 0, + "targetActivityId": 1004355, + "externalId": 0, + "creatorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "mediaUrlDds": "", + "active": true, + "mediaUrlPngMedium": "" +} +``` + +If the club does not exist, the response will contain an error: + +```json +[ + "activity:error-notFound" +] +``` + +If the player does not have enough permissions in the club to create folders, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` diff --git a/docs/live/club-management/create-map-review.md b/docs/live/club-management/create-map-review.md new file mode 100644 index 0000000..c8f9b61 --- /dev/null +++ b/docs/live/club-management/create-map-review.md @@ -0,0 +1,139 @@ +--- +name: Create club map review activity + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/map-review/create + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club where the map review activity should be created + required: true + body: + - name: name + type: string + description: The name of the new map review activity + max: 20 characters + required: true + - name: timeLimit + type: integer + description: The maximum time per map, in seconds + default: 180 + max: 3600 + - name: scalable + type: integer + description: Whether a new server should be created when the map review room is full (1) or not (0) + default: 1 + - name: maxPlayer + type: integer + description: The maximum number of players allowed in the map review room + default: 64 + max: 100 + - name: allowVoteSkipMap + type: integer + description: Whether to allow players to start a vote to skip the current map (1) or not (0) + default: 0 + - name: submissionLimitation + type: integer + description: Whether to allow players to only submit a single track per hour (1) or not (0) + default: 0 + - name: folderId + type: integer + description: The ID of the folder where the map review activity should be created + default: 0 +--- + +The request body is an object containing the map review details: + +```json +{ + "name": name, + "timeLimit": timeLimit, + "scalable": scalable, + "maxPlayer": maxPlayer, + "allowVoteSkipMap": allowVoteSkipMap, + "submissionLimitation": submissionLimitation, + "folderId": folderId +} +``` + +Creates a map review activity in a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. +- See the [glossary](/glossary#club-folders) for more information about folders. + +--- + +**Example request**: + +```plain +https://live-services.trackmania.nadeo.live/api/token/club/103034/map-review/create +``` + +```json +{ + "name": "My tracks", + "timeLimit": 180, + "scalable": 1, + "maxPlayer": 64, + "allowVoteSkipMap": 0, + "submissionLimitation": 0, + "folderId": 0 +} +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1772060908, + "clubName": "Fort's club", + "id": 1008026, + "scalable": true, + "public": true, + "game2webUrl": "https://www.trackmania.com/clubs/103034/track-reviews/1008026", + "activityId": 1008026, + "name": "My tracks", + "clubId": 103034, + "mediaUrlPngSmall": "", + "mediaUrl": "", + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "mapReviewUid": "club_103034_1008026", + "mediaUrlPngLarge": "", + "maxPlayer": 64, + "mediaTheme": "", + "popularityLevel": 0, + "submittedMapCount": 0, + "submissionLimitation": false, + "creatorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "timeLimit": 180, + "allowVoteSkipMap": false, + "mediaUrlDds": "", + "mediaUrlPngMedium": "" +} +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the authenticated account does not have enough permissions in the club to create a map review activity, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` diff --git a/docs/live/club-management/create-news.md b/docs/live/club-management/create-news.md new file mode 100644 index 0000000..71cd87b --- /dev/null +++ b/docs/live/club-management/create-news.md @@ -0,0 +1,110 @@ +--- +name: Create club news article + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/news/create + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club where the news article should be created + required: true + body: + - name: name + type: string + description: The name of the new news + max: 20 characters + required: true + - name: headline + type: string + description: The headline of the news article, displayed below the name + max: 40 characters + - name: body + type: string + description: The news body + max: 2000 characters + - name: folderId + type: integer + description: The ID of the folder where the news article should be created +--- + +The request body is an object containing the news article details: + +```json +{ + "name": name, + "headline": headline, + "body": body, + "folderId": folderId +} +``` + +Creates a news article in a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- The `body` field supports text styling, which does not count towards the maximum character length. See the [Text Styling documentation](https://wiki.trackmania.io/en/content-creation/text-styling) for more information about the supported styles and syntax. +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. +- See the [glossary](/glossary#club-folders) for more information about folders. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/103034/news/create +``` + +```json +{ + "name": "My news!", + "headline": "News for testing", + "body": "This is the body of an article created to test the endpoint!", + "folderId": 0 +} +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1771912390, + "mediaUrlJpgLarge": "", + "mediaUrlJpgMedium": "", + "clubName": "Fort's club", + "id": 1006858, + "name": "My news!", + "clubId": 103034, + "mediaUrl": "", + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "body": "This is the body of an article created to test the endpoint!", + "mediaTheme": "", + "creatorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "headline": "News for testing", + "mediaUrlJpgSmall": "", + "mediaUrlDds": "" +} +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the authenticated account does not have enough permissions in the club to create news articles, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` diff --git a/docs/live/club-management/create-ranking.md b/docs/live/club-management/create-ranking.md new file mode 100644 index 0000000..d53ebd6 --- /dev/null +++ b/docs/live/club-management/create-ranking.md @@ -0,0 +1,112 @@ +--- +name: Create club ranking + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/ranking/create + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club where the ranking should be created + required: true + body: + - name: name + type: string + description: The name of the new ranking + max: 20 characters + required: true + - name: name + type: string + description: The use case of the ranking (see remarks below) + required: true + - name: campaignId + type: integer + description: The campaignID of a campaign from the club (see remarks below) + - name: folderId + type: integer + description: The ID of the folder where the ranking should be created +--- + +The request body is an object containing the ranking details: + +```json +{ + "name": name, + "useCase": useCase, + "campaignId": campaignId, + "folderId": folderId +} +``` + +Creates a ranking in a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- The `useCase` parameter supports three cases: Current Quarterly Campaign (`"ranking-official"`), Daily Track / TOTD (`"ranking-daily"`), and Club Campaign (`"ranking-club"`). +- When creating a Club Campaign ranking, it is required to set the `campaignId` parameter to the campaignID of a campaign from the club. +- If the club campaign is not a campaign from the club, or it does not exist, the ranking will be created, but an error will be displayed in-game when accessing the ranking. +- See the [glossary](/glossary#club-folders) for more information about folders. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/103034/ranking/create +``` + +```json +{ + "name": "Winter ranks", + "useCase": "ranking-club", + "campaignId": 127610, + "folderId": 0 +} +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1771993468, + "clubName": "Fort's club", + "id": 1007578, + "campaignId": 127610, + "name": "Winter ranks", + "clubId": 103034, + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "creatorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "useCase": "ranking-club" +} +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the authenticated account does not have enough permissions in the club to create rankings, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` + +If the `useCase` parameter is invalid, the response will contain an error: + +```json +[ + "useCase:error-inArray" +] +``` diff --git a/docs/live/club-management/create-room.md b/docs/live/club-management/create-room.md new file mode 100644 index 0000000..0d7fa17 --- /dev/null +++ b/docs/live/club-management/create-room.md @@ -0,0 +1,282 @@ +--- +name: Create club room + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/room/create + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club where the room should be created + required: true + body: + - name: name + type: string + description: The name of the new room + max: 20 characters + required: true + - name: region + type: string + description: The region where the room will be hosted (see remarks below) + required: true + - name: maxPlayersPerServer + type: integer + description: The maximum number of players allowed in each server + required: true + - name: script + type: string + description: The game mode script to use for the maps in the room + required: true + - name: settings + type: object[] + description: A list of settings to set for the game mode + children: + - name: key + type: string + description: The name of the setting + required: true + - name: value + type: string + description: The value for the setting, as a string + required: true + - name: type + type: string + description: The primitive type of the setting + required: true + - name: maps + type: string[] + description: The list of maps for the room, identified by their `mapUid` + - name: scalable + type: integer + description: Whether a new server should be created when the room is full (1) or not (0) + default: 0 + - name: password + type: integer + description: Whether a password will be required to join the room (1) or not (0) + default: 0 + - name: shufflePlaylist + type: integer + description: Whether the list of maps should be shuffled each time the room is started (1) or not (0) + default: 0 + - name: folderId + type: integer + description: The ID of the folder where the room should be created +--- + +The request body is an object containing the room details: + +```json +{ + "name": name, + "region": region, + "maxPlayersPerServer": maxPlayersPerServer, + "script": script, + "settings": [ + { + "key": key, + "value": value, + "type": type + } + ], + "maps": maps, + "scalable": scalable, + "password": password, + "shufflePlaylist": shufflePlaylist, + "folderId": folderId +} +``` + +Creates a room in a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- Duplicated `mapUid` will be ignored when creating the room. +- See the [glossary](/glossary#room-regions) for a list of available regions. +- For more information about the supported game mode scripts that can be passed to the `script` parameter, including how to create your own, read the [Gamemode documentation](https://wiki.trackmania.io/en/ManiaScript/Advanced/Gamemode) in the Trackmania Wiki. +- When passing an invalid `script`, the room will fail to start, displaying an error in-game. +- For a list of supported `settings` for each game mode, alongside their type and values, read the [Gamemode Settings documentation](https://wiki.trackmania.io/en/dedicated-server/Usage/OfficialGameModesSettings) in the Trackmania Wiki. +- The password of the new room can be retrieved using the [Get club room password endpoint](/live/clubs/room-password). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. +- See the [glossary](/glossary#club-folders) for more information about folders. + +--- + +**Example request**: + +```plain +https://live-services.trackmania.nadeo.live/api/token/club/103034/room/create +``` + +```json +{ + "name": "Winter maps", + "region": "ca-central", + "maxPlayersPerServer": 8, + "script": "TrackMania/TM_TimeAttack_Online.Script.txt", + "settings": [ + { + "key": "S_TimeLimit", + "value": "1000", + "type": "integer" + }, + { + "key": "S_WarmUpNb", + "value": "1", + "type": "integer" + }, + { + "key": "S_WarmUpDuration", + "value": "60", + "type": "integer" + }, + { + "key": "S_WarmUpTimeout", + "value": "10", + "type": "integer" + }, + { + "key": "S_ChatTime", + "value": "5", + "type": "integer" + }, + { + "key": "S_ForceLapsNb", + "value": "2", + "type": "integer" + }, + { + "key": "S_EnableJoinLeaveNotifications", + "value": "false", + "type": "boolean" + } + ], + "maps": [ + "KRelvYHRjEQoqnkJ_Th8FLKzTsg", + "3LRPuWYIe85IJBbUcmIHkaSBuHh", + "7rtUBaBVpeaN080v5NgCksdEr2c" + ], + "scalable": 1, + "password": 1, + "shufflePlaylist": 1, + "folderId": 0 +} +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1771696181, + "clubName": "Fort's club", + "id": 1004641, + "activityId": 1004641, + "campaignId": null, + "name": "Winter maps", + "clubId": 103034, + "roomId": 395571, + "password": true, + "room": { + "id": 395571, + "scalable": true, + "serverInfo": null, + "scriptSettings": { + "S_ForceLapsNb": { + "key": "S_ForceLapsNb", + "value": "2", + "type": "integer" + }, + "S_WarmUpTimeout": { + "key": "S_WarmUpTimeout", + "value": "10", + "type": "integer" + }, + "S_WarmUpNb": { + "key": "S_WarmUpNb", + "value": "1", + "type": "integer" + }, + "S_WarmUpDuration": { + "key": "S_WarmUpDuration", + "value": "60", + "type": "integer" + }, + "S_TimeLimit": { + "key": "S_TimeLimit", + "value": "1000", + "type": "integer" + }, + "S_DecoImageUrl_WhoAmIUrl": { + "key": "S_DecoImageUrl_WhoAmIUrl", + "value": "/api/club/103034", + "type": "text" + }, + "S_ChatTime": { + "key": "S_ChatTime", + "value": "5", + "type": "integer" + }, + "S_EnableJoinLeaveNotifications": { + "key": "S_EnableJoinLeaveNotifications", + "value": "false", + "type": "boolean" + } + }, + "playerCount": 0, + "serverAccountId": "", + "name": "Winter maps", + "shufflePlaylist": false, + "region": "ca-central", + "maps": [ + "KRelvYHRjEQoqnkJ_Th8FLKzTsg", + "3LRPuWYIe85IJBbUcmIHkaSBuHh", + "7rtUBaBVpeaN080v5NgCksdEr2c" + ], + "script": "TrackMania/TM_TimeAttack_Online.Script.txt", + "maxPlayers": 8 + }, + "mediaUrlPngSmall": "", + "mediaUrl": "", + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "nadeo": true, + "mediaUrlPngLarge": "", + "mediaTheme": "", + "popularityLevel": 0, + "creatorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "playerServerLogin": null, + "mediaUrlDds": "", + "mediaUrlPngMedium": "" +} +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the authenticated account does not have enough permissions in the club to create rooms, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` + +If the `region` is invalid, the response will contain an error: + +```json +[ + "region:region not in available choice" +] +``` + +An invalid `mapUid` results in a `500` response code with an error object in the response body. diff --git a/docs/live/club-management/create-upload.md b/docs/live/club-management/create-upload.md new file mode 100644 index 0000000..b568b78 --- /dev/null +++ b/docs/live/club-management/create-upload.md @@ -0,0 +1,115 @@ +--- +name: Create club upload activity + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/bucket/create + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club where the upload activity should be created + required: true + body: + - name: name + type: string + description: The name of the new upload activity + max: 20 characters + required: true + - name: type + type: string + description: The type of upload activity to be created (see remarks below) + required: true + - name: folderId + type: integer + description: The ID of the folder where the upload activity should be created +--- + +The request body is an object containing the upload activity details: + +```json +{ + "name": name, + "type": type, + "folderId": folderId +} +``` + +Creates an upload activity in a club for maps, items, or skins. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- See the [glossary](/glossary#club-upload-activity-types) for a list of available upload types. +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. +- See the [glossary](/glossary#club-folders) for more information about folders. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/103034/bucket/create +``` + +**Example response**: + +```json +{ + "name": "My maps", + "type": "map-upload", + "folderId": 0 +} +``` + +```json +{ + "creationTimestamp": 1772159451, + "clubName": "Fort's test club", + "id": 1008748, + "name": "My maps", + "clubId": 103034, + "mediaUrlPngSmall": "", + "mediaUrl": "", + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "type": "map-upload", + "mediaUrlPngLarge": "", + "mediaTheme": "", + "popularityLevel": 0, + "bucketItemList": [], + "popularityValue": 0, + "creatorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "bucketItemCount": 0, + "mediaUrlDds": "", + "mediaUrlPngMedium": "" +} +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the authenticated account does not have enough permissions in the club to create upload activities, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` + +If the `type` parameter is invalid, the response will contain an error: + +```json +[ + "type:error-inArray" +] +``` diff --git a/docs/live/club-management/delete-activity.md b/docs/live/club-management/delete-activity.md new file mode 100644 index 0000000..909ff53 --- /dev/null +++ b/docs/live/club-management/delete-activity.md @@ -0,0 +1,67 @@ +--- +name: Delete club activity + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/activity/{activityId}/delete + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the activity belongs to + required: true + - name: activityId + type: integer + description: The ID of the activity to delete + required: true +--- + +Deletes an activity from a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- When deleting a folder with other activities inside it, they will be moved outside the folder. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/103034/activity/1003588/delete +``` + +**Example response**: + +```plain +Activity deleted +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the activity does not exist, the response will contain an error: + +```json +[ + "activity:error-notFound" +] +``` + +If the player does not have enough permissions in the club to delete activities, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` diff --git a/docs/live/club-management/delete-club.md b/docs/live/club-management/delete-club.md new file mode 100644 index 0000000..8ac73bc --- /dev/null +++ b/docs/live/club-management/delete-club.md @@ -0,0 +1,57 @@ +--- +name: Delete club + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/delete + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club to delete + required: true +--- + +Deletes a club the player has created. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- Deleting a club will also delete all its content, which will not be able to be recovered afterwards. +- Only the club creator can delete a club. +- Deleting a club will reset your tag and pinned club, regardless of the club deleted. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/131063/delete +``` + +**Example response**: + +```plain +Club deleted. +``` + +If the club does not exist or the player is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the player is not the creator of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notCreator" +] +``` diff --git a/docs/live/club-management/delete-member.md b/docs/live/club-management/delete-member.md new file mode 100644 index 0000000..f73e857 --- /dev/null +++ b/docs/live/club-management/delete-member.md @@ -0,0 +1,60 @@ +--- +name: Delete club member + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/member/{accountId}/delete + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the player is a member of + required: true + - name: accountId + type: string + description: The account ID of the member to be deleted + required: true +--- + +Deletes a member of a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- This endpoint can also be used for the authenticated account to leave clubs they do not own. +- When trying to leave a club the authenticated account is the creator of, the response will still return a `200` response code, but the account will not leave the club. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/383/member/69f31664-4252-48e0-a433-024c49caee8c/delete +``` + +**Example response**: + +```plain +Club member deleted +``` + +If the club or account does not exist, or the player is not a member of the club, the response will contain an error: + +```json +[ + "clubMember:error-notFound" +] +``` + +If the authenticated account is not an admin in the club and its account ID does not match the `accountId` parameter, the response will contain an error: + +```json +[ + "clubMemberRole:error-notAdmin" +] +``` diff --git a/docs/live/club-management/edit-activity.md b/docs/live/club-management/edit-activity.md new file mode 100644 index 0000000..ba0b47d --- /dev/null +++ b/docs/live/club-management/edit-activity.md @@ -0,0 +1,152 @@ +--- +name: Edit club activity + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/activity/{activityId}/edit + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the activity belongs to + required: true + - name: activityId + type: integer + description: The ID of the activity to be edited + required: true + body: + - name: name + type: string + description: The new name of the activity + - name: active + type: integer + description: Whether the activity should be active (1) or deactivated (0) + - name: featured + type: integer + description: Whether the activity should be featured in the club (1) or not (0) + - name: folderId + type: integer + description: The ID of the folder in the club where the activity should be moved + - name: mediaTheme + type: string + description: The name of the theme preset to use for the activity, in lower-case + - name: position + type: integer + description: The position of the activity in the club's activities list + - name: public + type: integer + description: Whether the activity should be public (1) or private (0) +--- + +The request body is an object with the activity details to be edited: + +```json +{ + "name": name, + "active": active, + "featured": featured, + "folderId": folderId, + "mediaTheme": mediaTheme, + "position": position, + "public": public +} +``` + +Edits an activity in a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- To move an activity out of a folder, set `folderID` to `0`. +- A valid `position` depends on the other activities in the club, including deactivated and deleted ones. It's recommended to use one of the positions returned by the [Get club activities Live endpoint](/live/clubs/activities.md). +- A list of theme presets that can be used for the `mediaTheme` parameter can be found in the following directory when selecting an image for a club activity: `Manialinks\Nadeo\CMGame\OfficialThemes`. +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. +- See the [glossary](/glossary#club-folders) for more information about folders. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/103034/activity/1003588/edit +``` + +```json +{ + "name": "My uploaded maps", + "active": 1, + "featured": 1, + "folderId": 0, + "mediaTheme": "mirage", + "position": 0, + "public": 0 +} +``` + +**Example response**: + +```json +{ + "id": 1003588, + "folderId": null, + "public": false, + "activityId": 1003588, + "campaignId": 0, + "name": "My uploaded maps", + "clubId": 103034, + "password": false, + "featured": true, + "activityType": "map-upload", + "mediaUrlPngSmall": "", + "mediaUrl": "", + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "editionTimestamp": 1771560553, + "mediaUrlPngLarge": "", + "itemsCount": 0, + "mediaTheme": "mirage", + "position": 0, + "targetActivityId": 1003588, + "externalId": 0, + "creatorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "mediaUrlDds": "", + "active": true, + "mediaUrlPngMedium": "" +} +``` + +If the club / activity does not exist or the player is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the player does not have enough permissions in the club to edit activities, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` + +If the `folderID` does not exist, the response will contain an error: + +```json +[ + "folder:error-notFound" +] +``` + +If the `position` is invalid, or the activity is already at that position, the response will contain an error: + +```json +[ + "position:error-wrongPosition" +] +``` diff --git a/docs/live/club-management/edit-campaign.md b/docs/live/club-management/edit-campaign.md new file mode 100644 index 0000000..b632cf6 --- /dev/null +++ b/docs/live/club-management/edit-campaign.md @@ -0,0 +1,200 @@ +--- +name: Edit club campaign + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/campaign/{campaignId}/edit + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the campaign belongs to + required: true + - name: campaignId + type: integer + description: The ID of the campaign to be edited + required: true + body: + - name: name + type: string + description: The new name of the campaign + max: 20 characters + - name: playlist + type: object[] + description: A list of maps, with their positions and UIDs + children: + - name: position + type: integer + description: The position of the map in the campaign (see remarks below) + - name: mapUid + type: string + description: The UID of a specific map +--- + +The request body is an object containing the campaign details: + +```json +{ + "name": name, + "playlist": [ + { + "position": position, + "mapUid": mapUid + } + ] +} +``` + +Edits a campaign in a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- The position of the maps in the campaign seems to be determined by their order in the `playlist` array in the request body, rather than by their `position` parameter. It is still recommended to pass the desired position. +- If a map is missing its `mapUid` or `position`, the campaign will be edited, but the map will be skipped. +- Maps used for this endpoint must be uploaded to Nadeo's servers beforehand. +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/103034/campaign/126985/edit +``` + +```json +{ + "name": "RPG maps", + "playlist": [ + { + "position": 0, + "mapUid": "zx45UUBTayedFisP7N_wYWZa3Ih" + }, + { + "position": 1, + "mapUid": "F082FKYgeG0OO8XlUSzE5uaOgL0" + } + ] +} +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1771568272, + "clubName": "Fort's club", + "id": 1003600, + "clubDecalUrl": "", + "publicationTimestamp": 1771568272, + "activityId": 1003600, + "campaignId": 126985, + "name": "RPG maps", + "clubId": 103034, + "mediaUrlPngSmall": "", + "mediaUrl": "", + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "mediaUrlPngLarge": "", + "campaign": { + "day": -1, + "id": 126985, + "video": false, + "publicationTimestamp": 1771568272, + "monthDay": -1, + "color": "", + "name": "RPG maps", + "clubId": 103034, + "month": -1, + "endTimestamp": 0, + "monthYear": -1, + "rankingSentTimestamp": null, + "mediaUrl": "", + "startTimestamp": 1771568272, + "editionTimestamp": 1771568272, + "leaderboardGroupUid": "NLS-RHoGdQjhHjyIHHtpmLIaFVS4616v7M8gbwG", + "seasonUid": "NLS-RHoGdQjhHjyIHHtpmLIaFVS4616v7M8gbwG", + "categories": [ + { + "name": "RPG maps", + "position": 0, + "length": 5 + } + ], + "year": -1, + "media": { + "decalUrl": "", + "popUpImageUrl": "", + "liveButtonForegroundUrl": "", + "liveButtonBackgroundUrl": "", + "buttonBackgroundUrl": "", + "popUpBackgroundUrl": "", + "buttonForegroundUrl": "" + }, + "published": true, + "useCase": 2, + "playlist": [ + { + "id": 1515297, + "mapUid": "zx45UUBTayedFisP7N_wYWZa3Ih", + "position": 0 + }, + { + "id": 1515298, + "mapUid": "F082FKYgeG0OO8XlUSzE5uaOgL0", + "position": 1 + } + ], + "week": -1, + "latestSeasons": [ + { + "uid": "NLS-RHoGdQjhHjyIHHtpmLIaFVS4616v7M8gbwG", + "campaignId": 126985, + "name": "RPG maps", + "endTimestamp": 0, + "startTimestamp": 1771568272, + "relativeEnd": 0, + "active": true, + "relativeStart": -217 + } + ] + }, + "mediaTheme": "", + "popularityLevel": 0, + "creatorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "mediaUrlDds": "", + "mapsCount": 2, + "mediaUrlPngMedium": "" +} +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the campaign does not exist, the response will contain an error: + +```json +[ + "activity:error-notFound" +] +``` + +If the authenticated account does not have enough permissions in the club to edit campaigns, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` + +An invalid `mapUid` results in a `500` response code with an error object in the response body. diff --git a/docs/live/club-management/edit-club.md b/docs/live/club-management/edit-club.md new file mode 100644 index 0000000..a761ad6 --- /dev/null +++ b/docs/live/club-management/edit-club.md @@ -0,0 +1,208 @@ +--- +name: Edit club + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/edit + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club to be edited + required: true + body: + - name: name + type: string + description: The new name of the club + min: 3 characters + max: 20 characters + - name: state + type: string + description: The privacy level of the club (see remarks below) + - name: tag + type: string + description: The club tag that can be displayed in-game next to the player's display name. + max: 5 characters + - name: description + type: string + description: A description of the club + max: 200 characters + - name: iconTheme + type: string + description: The name of the theme preset for the icon displayed in the list of clubs in-game, in lower case + - name: decalTheme + type: string + description: The name of the theme preset for the image displayed at the start, checkpoints, and finishes, in lower case + - name: verticalTheme + type: string + description: The name of the theme preset for the vertical image displayed in My Clubs list, in lower case + - name: backgroundTheme + type: string + description: The name of the theme preset for the background displayed in the club details page, in lower case + - name: screen8x1Theme + type: string + description: The name of the theme preset for the image displayed on the stadium's bleachers, in lower case + - name: screen16x1Theme + type: string + description: The name of the theme preset for the image displayed on the stadium's banners below the big screen, in lower case + - name: screen16x9Theme + type: string + description: The name of the theme preset for the image displayed on the stadium's big screen, in lower case +--- + +The request body is an object containing the club details: + +```json +{ + "name": name, + "state": state, + "tag": tag, + "description": description, + "iconTheme": iconTheme, + "decalTheme": decalTheme, + "verticalTheme": verticalTheme, + "backgroundTheme": backgroundTheme, + "screen8x1Theme": screen8x1Theme, + "screen16x1Theme": screen16x1Theme, + "screen16x9Theme": screen16x9Theme +} +``` + +Edits a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- See the [glossary](/glossary#club-privacy-levels) for a list of available privacy levels. +- When setting the `state` privacy level to `"public"`, players with a pending member request will automatically join the club. +- A list of theme presets that can be used for the theme parameters can be found in the following directory when selecting an image for a club activity: `Manialinks\Nadeo\CMGame\OfficialThemes`. +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. +- The `tag` field supports text styling, which does not count towards the maximum character length. See the [Text Styling documentation](https://wiki.trackmania.io/en/content-creation/text-styling) for more information about the supported styles and syntax. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/131063/edit +``` + +```json +{ + "name": "Edited club", + "tag": "TEST", + "description": "This is an edited description", + "state": "private-open", + "iconTheme": "hungry", + "decalTheme": "hungry", + "backgroundTheme": "honor", + "verticalTheme": "honor", + "screen8x1Theme": "animals", + "screen16x1Theme": "animals", + "screen16x9Theme": "animals" +} +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1771820094, + "walletUid": "559cd73b-de9d-45df-82b6-b36ae04bd668", + "id": 131063, + "decalUrl": "", + "decalSponsor4x1UrlPngLarge": "", + "backgroundUrlJpgLarge": "", + "decalSponsor4x1UrlDds": "", + "decalTheme": "hungry", + "screen16x1Url": "", + "name": "Edited club", + "screen64x41Theme": "animals", + "screen64x41UrlDds": "", + "featured": false, + "decalUrlPngMedium": "", + "screen64x41UrlPngLarge": "", + "screen16x1UrlDds": "", + "verified": false, + "screen16x9Theme": "animals", + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "iconUrlPngMedium": "", + "backgroundUrlDds": "", + "editionTimestamp": 1771820095, + "backgroundUrlJpgSmall": "", + "tag": "TEST", + "backgroundUrlJpgMedium": "", + "verticalUrlPngMedium": "", + "metadata": "", + "decalUrlPngSmall": "", + "verticalTheme": "honor", + "backgroundTheme": "honor", + "verticalUrlPngSmall": "", + "iconUrlPngSmall": "", + "iconUrl": "", + "popularityLevel": 0, + "screen8x1UrlDds": "", + "verticalUrlPngLarge": "", + "screen16x9Url": "", + "screen64x41UrlPngMedium": "", + "screen16x1UrlPngMedium": "", + "screen8x1UrlPngSmall": "", + "authorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "screen16x1UrlPngLarge": "", + "state": "private-open", + "screen16x9UrlDds": "", + "verticalUrlDds": "", + "logoUrl": "", + "screen8x1UrlPngMedium": "", + "screen16x9UrlPngLarge": "", + "screen64x41Url": "", + "screen16x9UrlPngSmall": "", + "screen16x9UrlPngMedium": "", + "description": "This is an edited description", + "decalSponsor4x1UrlPngSmall": "", + "screen8x1Theme": "animals", + "screen8x1UrlPngLarge": "", + "verticalUrl": "", + "screen16x1Theme": "animals", + "iconTheme": "hungry", + "screen64x41UrlPngSmall": "", + "decalUrlPngLarge": "", + "iconUrlPngLarge": "", + "decalUrlDds": "", + "decalSponsor4x1Url": "", + "screen8x1Url": "", + "iconUrlDds": "", + "screen16x1UrlPngSmall": "", + "decalSponsor4x1UrlPngMedium": "", + "backgroundUrl": "" +} +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the authenticated account does not have enough permissions in the club to edit it, the response will contain an error: + +```json +[ + "clubMemberRole:error-notAdmin" +] +``` + +If the `state` parameter is invalid, the response will contain an error: + +```json +[ + "state:error-inArray" +] +``` diff --git a/docs/live/club-management/edit-map-review.md b/docs/live/club-management/edit-map-review.md new file mode 100644 index 0000000..37e8ddc --- /dev/null +++ b/docs/live/club-management/edit-map-review.md @@ -0,0 +1,138 @@ +--- +name: Edit club map review activity + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/map-review/{mapReviewId}/edit + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club where the map review activity should be created + required: true + - name: mapReviewId + type: integer + description: The ID of the map review activity to be edited + required: true + body: + - name: name + type: string + description: The new name of the map review activity + max: 20 characters + - name: timeLimit + type: integer + description: The maximum time per map, in seconds + max: 3600 + - name: scalable + type: integer + description: Whether a new server should be created when the map review room is full (1) or not (0) + - name: maxPlayer + type: integer + description: The maximum number of players allowed in the map review room + max: 100 + - name: allowVoteSkipMap + type: integer + description: Whether to allow players to start a vote to skip the current map (1) or not (0) + - name: submissionLimitation + type: integer + description: Whether to allow players to only submit a single track per hour (1) or not (0) +--- + +The request body is an object containing the map review details: + +```json +{ + "name": name, + "timeLimit": timeLimit, + "scalable": scalable, + "maxPlayer": maxPlayer, + "allowVoteSkipMap": allowVoteSkipMap, + "submissionLimitation": submissionLimitation +} +``` + +Edits a map review activity in a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. + +--- + +**Example request**: + +```plain +https://live-services.trackmania.nadeo.live/api/token/club/103034/map-review/1008026/edit +``` + +```json +{ + "name":"Edited title", + "timeLimit": 300, + "scalable": 0, + "maxPlayer": 48, + "allowVoteSkipMap":1, + "submissionLimitation": 1 +} +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1772060908, + "clubName": "Fort's club", + "id": 1008026, + "scalable": false, + "public": true, + "game2webUrl": "https://www.trackmania.com/clubs/103034/track-reviews/1008026", + "activityId": 1008026, + "name": "Edited title", + "clubId": 103034, + "mediaUrlPngSmall": "", + "mediaUrl": "", + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "mapReviewUid": "club_103034_1008026", + "mediaUrlPngLarge": "", + "maxPlayer": 48, + "mediaTheme": "", + "popularityLevel": 0, + "submittedMapCount": 0, + "submissionLimitation": true, + "creatorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "timeLimit": 300, + "allowVoteSkipMap": true, + "mediaUrlDds": "", + "mediaUrlPngMedium": "" +} +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the map review activity does not exist, the response will contain an error: + +```json +[ + "activity:error-notFound" +] +``` + +If the authenticated account does not have enough permissions in the club to edit a map review activity, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` diff --git a/docs/live/club-management/edit-member.md b/docs/live/club-management/edit-member.md new file mode 100644 index 0000000..06f860c --- /dev/null +++ b/docs/live/club-management/edit-member.md @@ -0,0 +1,112 @@ +--- +name: Edit club member + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/member/{accountId}/edit + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the members belongs to + required: true + - name: accountId + type: integer + description: The account ID of the club member + required: true + body: + - name: role + type: string + description: The new role of the member in the club +--- + +The request body is an object containing the member details: + +```json +{ + "role": role +} +``` + +Edits a member in the club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- The `role` parameter supports three roles: Member (`"Member"`), Content Creator (`"Content Creator"`), and Admin (`"Admin"`). +- For more information about member roles, including their permissions, read the [Club Organisation page](https://wiki.trackmania.io/en/content-creation/club-organisation#member-management) in the Trackmania wiki. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/103034/member/5b4d42f4-c2de-407d-b367-cbff3fe817bc/edit +``` + +```json +{ + "role": "Admin" +} +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1771820894, + "accountId": "5b4d42f4-c2de-407d-b367-cbff3fe817bc", + "clubId": 131063, + "moderator": false, + "vip": true, + "hasFeatured": false, + "useTag": false, + "pin": false, + "role": "Admin" +} +``` + +If the `accountID` is invalid or does not belong to a member of the club, the response will contain an error: + +```json +[ + "clubMember:error-notFound" +] +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the authenticated account does not have enough permissions in the club to manage members, the response will contain an error: + +```json +[ + "clubMemberRole:error-notAdmin" +] +``` + +If trying to set a member's role to `"Creator"`, the response will contain an error: + +```json +[ + "role:error-creatorForbidden" +] +``` + +if the `role` parameter is invalid, the response will contain an error: + +```json +[ + "role:error-inArray" +] +``` diff --git a/docs/live/club-management/edit-news.md b/docs/live/club-management/edit-news.md new file mode 100644 index 0000000..b38402c --- /dev/null +++ b/docs/live/club-management/edit-news.md @@ -0,0 +1,115 @@ +--- +name: Edit club news article + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/news/{newsId}/edit + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the news article belongs to + required: true + - name: newsId + type: integer + description: The ID of the news article to be edited + required: true + body: + - name: name + type: string + description: The new name of the news article + max: 20 characters + - name: headline + type: string + description: The headline of the news article, displayed below the name + max: 40 characters + - name: body + type: string + description: The news article body + max: 2000 characters +--- + +The request body is an object containing the news article details: + +```json +{ + "name": name, + "headline": headline, + "body": body +} +``` + +Edits a news article in a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. +- The `body` field supports text styling, which does not count towards the maximum character length. See the [Text Styling documentation](https://wiki.trackmania.io/en/content-creation/text-styling) for more information about the supported styles and syntax. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/103034/news/1006858/edit +``` + +```json +{ + "name": "My edited news!", + "headline": "Edited news for testing", + "body": "This is me editing the body!" +} +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1771912390, + "mediaUrlJpgLarge": "", + "mediaUrlJpgMedium": "", + "clubName": "Fort's club", + "id": 1006858, + "name": "My edited news!", + "clubId": 103034, + "mediaUrl": "", + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "body": "This is me editing the body!", + "mediaTheme": "", + "creatorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "headline": "Edited news for testing", + "mediaUrlJpgSmall": "", + "mediaUrlDds": "" +} +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the news article does not exist, the response will contain an error: + +```json +[ + "activity:error-notFound" +] +``` + +If the authenticated account does not have enough permissions in the club to edit news articles, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` diff --git a/docs/live/club-management/edit-room.md b/docs/live/club-management/edit-room.md new file mode 100644 index 0000000..00503e2 --- /dev/null +++ b/docs/live/club-management/edit-room.md @@ -0,0 +1,241 @@ +--- +name: Edit club room + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/room/{roomId}/edit + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the room belongs to + required: true + - name: roomId + type: integer + description: The ID of the room to be edited + required: true + body: + - name: name + type: string + description: The new name of the room + max: 20 characters + - name: region + type: string + description: The region where the room will be hosted (see remarks below) + - name: maxPlayersPerServer + type: integer + description: The maximum number of players allowed in each server + - name: script + type: string + description: The game mode script to use for the maps in the room + - name: settings + type: object[] + description: A list of settings to edit for the game mode + children: + - name: key + type: string + description: The name of the setting + required: true + - name: value + type: string + description: The value for the setting, as a string + required: true + - name: type + type: string + description: The primitive type of the setting + required: true + - name: maps + type: string[] + description: The list of maps for the room, identified by their `mapUid` + - name: scalable + type: integer + description: Whether a new server should be created when the room is full (1) or not (0) + - name: shufflePlaylist + type: integer + description: Whether the list of maps should be shuffled each time the room is started (1) or not (0) +--- + +The request body is an object with the room details to be edited: + +```json +{ + "name": name, + "region": region, + "maxPlayersPerServer": maxPlayersPerServer, + "script": script, + "settings": [ + { + "key": key, + "value": value, + "type": type + } + ], + "maps": maps, + "scalable": scalable, + "shufflePlaylist": shufflePlaylist +} +``` + +Edits a club room. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- Duplicated `mapUid` will be ignored when editing the room. +- See the [glossary](/glossary#room-regions) for a list of available regions. +- For more information about the supported game mode scripts that can be passed to the `script` parameter, including how to create your own, read the [Gamemode documentation](https://wiki.trackmania.io/en/ManiaScript/Advanced/Gamemode) in the Trackmania Wiki. +- When passing an invalid `script`, the room will stop on map switch and fail to restart, displaying an error in-game. +- For a list of supported `settings` for each game mode, alongside their type and values, read the [Gamemode Settings documentation](https://wiki.trackmania.io/en/dedicated-server/Usage/OfficialGameModesSettings) in the Trackmania Wiki. +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/103034/room/1004641/edit +``` + +```json +{ + "name": "Winter 2026", + "region": "eu-west", + "maxPlayersPerServer": 11, + "script": "TrackMania/TM_TimeAttack_Online.Script.txt", + "settings": [ + { + "key": "S_TimeLimit", + "value": "-1", + "type": "integer" + }, + { + "key": "S_ForceLapsNb", + "value": "-1", + "type": "integer" + } + ], + "maps": [ + "8elIE5tBmTkuxJaX9bniSkPkU45", + "fAEmqACIh7yFtNEFZWZwlqV8qvh" + ], + "scalable": 0, + "shufflePlaylist": 1 +} +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1771696181, + "clubName": "Fort's club", + "id": 1004641, + "activityId": 1004641, + "campaignId": null, + "name": "Winter testing", + "clubId": 103034, + "roomId": 395571, + "password": true, + "room": { + "id": 395571, + "scalable": true, + "serverInfo": null, + "scriptSettings": { + "S_ForceLapsNb": { + "key": "S_ForceLapsNb", + "value": "2", + "type": "integer" + }, + "S_WarmUpTimeout": { + "key": "S_WarmUpTimeout", + "value": "10", + "type": "integer" + }, + "S_WarmUpNb": { + "key": "S_WarmUpNb", + "value": "1", + "type": "integer" + }, + "S_WarmUpDuration": { + "key": "S_WarmUpDuration", + "value": "60", + "type": "integer" + }, + "S_TimeLimit": { + "key": "S_TimeLimit", + "value": "1000", + "type": "integer" + }, + "S_DecoImageUrl_WhoAmIUrl": { + "key": "S_DecoImageUrl_WhoAmIUrl", + "value": "/api/club/103034", + "type": "text" + }, + "S_ChatTime": { + "key": "S_ChatTime", + "value": "5", + "type": "integer" + }, + "S_EnableJoinLeaveNotifications": { + "key": "S_EnableJoinLeaveNotifications", + "value": "false", + "type": "boolean" + } + }, + "playerCount": 0, + "serverAccountId": "", + "name": "Winter testing", + "shufflePlaylist": true, + "region": "eu-west", + "maps": [ + "KRelvYHRjEQoqnkJ_Th8FLKzTsg", + "3LRPuWYIe85IJBbUcmIHkaSBuHh", + "7rtUBaBVpeaN080v5NgCksdEr2c" + ], + "script": "TrackMania/TM_TimeAttack_Online.Script.txt", + "maxPlayers": 11 + }, + "mediaUrlPngSmall": "", + "mediaUrl": "", + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "nadeo": true, + "mediaUrlPngLarge": "", + "mediaTheme": "", + "popularityLevel": 0, + "creatorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "playerServerLogin": null, + "mediaUrlDds": "", + "mediaUrlPngMedium": "" +} +``` + +If the club / room does not exist or the player is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the player does not have enough permissions in the club to edit rooms, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` + +If the `region` is invalid, the response will contain an error: + +```json +[ + "region:region not in available choice" +] +``` + +An invalid `mapUid` results in a `500` response code with an error object in the response body. diff --git a/docs/live/club-management/member-requests.md b/docs/live/club-management/member-requests.md new file mode 100644 index 0000000..547fae4 --- /dev/null +++ b/docs/live/club-management/member-requests.md @@ -0,0 +1,95 @@ +--- +name: Get club pending member requests + +url: https://live-services.trackmania.nadeo.live +method: GET +route: /api/token/club/{clubId}/member/request?length={length}&offset={offset} + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: string + description: The club's ID + required: true + query: + - name: length + type: integer + description: The number of member requests to retrieve + required: true + - name: offset + type: integer + description: The number of member requests to skip + required: true +--- + +Gets a list of pending member requests for a club. + +--- + +**Remarks**: + +- This endpoint is only useful for clubs with their privacy level set to `"private-open"`. For other privacy settings, the endpoint will return an empty list. + +--- + +**Example request**: + +```plain +GET https://live-services.trackmania.nadeo.live/api/token/club/354/member/request?offset=0&length=3 +``` + +**Example response**: + +```json +{ + "clubMemberList": [ + { + "creationTimestamp": 1747349376, + "accountId": "49745547-c2c6-4800-8860-2471744fb1f7", + "clubId": 354, + "moderator": false, + "vip": false, + "hasFeatured": false, + "useTag": false, + "pin": false, + "role": "Apply" + }, + { + "creationTimestamp": 1748780844, + "accountId": "860ecb27-7e4b-4275-a0ad-578d99a87a55", + "clubId": 354, + "moderator": false, + "vip": false, + "hasFeatured": false, + "useTag": false, + "pin": false, + "role": "Apply" + }, + { + "creationTimestamp": 1750991529, + "accountId": "cbca399b-0f87-42fe-bd12-a51a843050fb", + "clubId": 354, + "moderator": false, + "vip": false, + "hasFeatured": false, + "useTag": false, + "pin": false, + "role": "Apply" + } + ], + "maxPage": 10, + "itemCount": 28 +} +``` + +If the club does not exist or support requests, the response will contain an empty list of pending member requests: + +```json +{ + "clubMemberList": [], + "maxPage": 0, + "itemCount": 0 +} +``` diff --git a/docs/live/club-management/remove-from-upload.md b/docs/live/club-management/remove-from-upload.md new file mode 100644 index 0000000..3d01b25 --- /dev/null +++ b/docs/live/club-management/remove-from-upload.md @@ -0,0 +1,89 @@ +--- +name: Remove items from club upload activity + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/bucket/{bucketId}/remove + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the upload activity belongs to + required: true + - name: bucketId + type: integer + description: The ID of the upload activity where the items should be removed from + required: true + body: + - name: itemIdList + type: string[] + description: A list of items to remove from the upload activity, identified by their ID (see remarks below) + required: true +--- + +The request body is an object containing the items to be removed: + +```json +{ + "itemIdList": itemIdList +} +``` + +Removes a list of maps, items, or skins from an upload activity in a club. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- The IDs needed for the `itemIdList` parameter depend on the type of upload activity requested. For maps uploads, it requires their `mapUid`, while skins and items require their `skinID` and `itemID`, respectively. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/103034/bucket/1009342/remove +``` + +```json +{ + "itemIdList": [ + "nHC4rwnDO4gGNsFdfzH_lqglXK9", + "3klKca5nVUdW6TPuSzqv4xAjuse" + ] +} +``` + +**Example response**: + +```plain +Items removed. +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the upload activity does not exist, the response will contain an error: + +```json +[ + "activity:error-notFound" +] +``` + +If the authenticated account does not have enough permissions in the club to edit upload activities, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` diff --git a/docs/live/club-management/set-vip.md b/docs/live/club-management/set-vip.md new file mode 100644 index 0000000..0e24afe --- /dev/null +++ b/docs/live/club-management/set-vip.md @@ -0,0 +1,77 @@ +--- +name: Set VIP club member + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/vip/{accountId}/set + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club where the user should become VIP + required: true + - name: accountId + type: integer + description: The account ID of the club member + required: true +--- + +Sets a club member as a VIP. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- VIP members will be displayed in the Club VIP leaderboard in-game while playing a map. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/131063/vip/69f31664-4252-48e0-a433-024c49caee8c/set +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1771820094, + "accountId": "69f31664-4252-48e0-a433-024c49caee8c", + "clubId": 131063, + "moderator": false, + "vip": true, + "hasFeatured": false, + "useTag": false, + "pin": false, + "role": "Creator" +} +``` + +If the `accountID` is invalid or does not belong to a member of the club, the response will contain an error: + +```json +[ + "clubMember:error-notFound" +] +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the authenticated account does not have enough permissions in the club to manage VIP members, the response will contain an error: + +```json +[ + "clubMemberRole:error-notAdmin" +] +``` diff --git a/docs/live/club-management/unset-vip.md b/docs/live/club-management/unset-vip.md new file mode 100644 index 0000000..fa0a44f --- /dev/null +++ b/docs/live/club-management/unset-vip.md @@ -0,0 +1,76 @@ +--- +name: Unset VIP club member + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/vip/{accountId}/unset + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club where the user should stop being VIP + required: true + - name: accountId + type: integer + description: The account ID of the club member + required: true +--- + +Removes a club member as a VIP. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/131063/vip/69f31664-4252-48e0-a433-024c49caee8c/unset +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1771820094, + "accountId": "69f31664-4252-48e0-a433-024c49caee8c", + "clubId": 131063, + "moderator": false, + "vip": false, + "hasFeatured": false, + "useTag": false, + "pin": false, + "role": "Creator" +} +``` + +If the `accountId` is invalid or does not belong to a member of the club, the response will contain an error: + +```json +[ + "clubMember:error-notFound" +] +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the authenticated account does not have enough permissions in the club to manage VIP members, the response will contain an error: + +```json +[ + "clubMemberRole:error-notAdmin" +] +``` diff --git a/docs/live/clubs/activities.md b/docs/live/clubs/activities.md index c798e27..4722c2c 100644 --- a/docs/live/clubs/activities.md +++ b/docs/live/clubs/activities.md @@ -38,7 +38,7 @@ Gets a list of club activities, including news, rooms, campaigns, and others. **Remarks**: - Omitting the `active` parameter implicitly requests both enabled and disabled activities. For clubs you are not an admin of, `active` needs to be explicitly set to `true` because only admins are allowed to see disabled activities - otherwise you'll get an error complaining that you're not a member/admin of the club. -- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png` versions are available using separate fields (see example below for reference). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. - By default, all activities (including ones nested in folders) are returned. To only retrieve activities in a specific folder, use `folderId` to filter them. Setting `folderId` to `0` only returns activities outside of folders. --- diff --git a/docs/live/clubs/campaign-by-id.md b/docs/live/clubs/campaign-by-id.md index 1ef3aab..e03372a 100644 --- a/docs/live/clubs/campaign-by-id.md +++ b/docs/live/clubs/campaign-by-id.md @@ -25,7 +25,7 @@ Gets the details of a specific club campaign. **Remarks**: -- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png` versions are available using separate fields (see example below for reference). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. --- diff --git a/docs/live/clubs/campaigns.md b/docs/live/clubs/campaigns.md index e13cc3e..48d7fb2 100644 --- a/docs/live/clubs/campaigns.md +++ b/docs/live/clubs/campaigns.md @@ -29,7 +29,7 @@ Gets a list of club campaigns. **Remarks**: -- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png` versions are available using separate fields (see example below for reference). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. - This endpoint does not return all available club campaigns. When excluding the `name` parameter, it returns all verified clubs' campaigns - otherwise the response is limited to 200 campaigns. --- diff --git a/docs/live/clubs/club.md b/docs/live/clubs/club.md index aea8d2b..03a948e 100644 --- a/docs/live/clubs/club.md +++ b/docs/live/clubs/club.md @@ -21,7 +21,7 @@ Gets information for the specified club. **Remarks**: -- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. --- diff --git a/docs/live/clubs/clubs-mine.md b/docs/live/clubs/clubs-mine.md index e54bf42..5ca996b 100644 --- a/docs/live/clubs/clubs-mine.md +++ b/docs/live/clubs/clubs-mine.md @@ -26,7 +26,7 @@ Gets clubs that you are a member of. **Remarks**: - This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts) as the response depends on a specific user's club memberships. -- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. --- @@ -118,7 +118,7 @@ GET https://live-services.trackmania.nadeo.live/api/token/club/mine?length=1&off } ``` -If you aren't a member of any clubs, the reponse will contain an empty list: +If you aren't a member of any clubs, the response will contain an empty list: ```json { diff --git a/docs/live/clubs/clubs.md b/docs/live/clubs/clubs.md index 40f1b50..13e2da4 100644 --- a/docs/live/clubs/clubs.md +++ b/docs/live/clubs/clubs.md @@ -29,7 +29,7 @@ Gets a list of clubs. **Remarks**: -- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. - This endpoint does not return all available clubs. When excluding the `name` parameter, it returns all verified clubs - otherwise the response is limited to 200 clubs. --- diff --git a/docs/live/clubs/join-club.md b/docs/live/clubs/join-club.md new file mode 100644 index 0000000..9470d6d --- /dev/null +++ b/docs/live/clubs/join-club.md @@ -0,0 +1,67 @@ +--- +name: Join a club + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/member/create + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the player will join + required: true +--- + +Join a club as a new member. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- If the club is private, but accepts requests, the `role` field in the response body will be `"Apply"`. +- If the current authenticated account has already joined the club, the endpoint will return the member information. +- To leave a club you have joined, you can use the [Delete club member Live endpoint](/live/club-management/delete-member.md). + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/103034/member/create +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1771819382, + "accountId": "69f31664-4252-48e0-a433-024c49caee8c", + "clubId": 103034, + "moderator": false, + "vip": false, + "hasFeatured": false, + "useTag": false, + "pin": false, + "role": "Member" +} +``` + +If the club does not exist, the response will contain an error: + +```json +[ + "club:error-notFound" +] +``` + +If the club is private, the response will contain an error: + +```json +[ + "clubState:error-wrongState" +] +``` diff --git a/docs/live/clubs/map-review-by-id.md b/docs/live/clubs/map-review-by-id.md new file mode 100644 index 0000000..8a937ed --- /dev/null +++ b/docs/live/clubs/map-review-by-id.md @@ -0,0 +1,73 @@ +--- +name: Get map review activity by ID + +url: https://live-services.trackmania.nadeo.live +method: GET +route: /api/token/club/{clubId}/map-review/{mapReviewId} + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the map review activity belongs to + required: true + - name: mapReviewId + type: integer + description: The ID of the map review activity to be requested + required: true +--- + +Gets the details of a specific map review activity. + +--- + +**Remarks**: + +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. + +**Example request**: + +```plain +GET https://live-services.trackmania.nadeo.live/api/token/club/31644/map-review/208777 +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1632597591, + "clubName": "TMA.gg", + "id": 208777, + "scalable": false, + "public": true, + "game2webUrl": "https://www.trackmania.com/clubs/31644/track-reviews/208777", + "activityId": 208777, + "name": "TMA map testing", + "clubId": 31644, + "mediaUrlPngSmall": "https://trackmania-prod-media-s3.cdn.ubi.com/media/image/live-api/089462af-7f9e-43cc-a561-593bbed3e1f2/png/small.png?timestamp=1705440002.png", + "mediaUrl": "https://trackmania-prod-media-s3.cdn.ubi.com/media/image/live-api/089462af-7f9e-43cc-a561-593bbed3e1f2/png/large.png?timestamp=1705440002.png", + "latestEditorAccountId": "abdc0576-fae7-4b31-96dc-539b8cda095f", + "mapReviewUid": "club_31644_208777", + "mediaUrlPngLarge": "https://trackmania-prod-media-s3.cdn.ubi.com/media/image/live-api/089462af-7f9e-43cc-a561-593bbed3e1f2/png/large.png?timestamp=1705440002.png", + "maxPlayer": 64, + "mediaTheme": "", + "popularityLevel": 0, + "submittedMapCount": 1035, + "submissionLimitation": false, + "creatorAccountId": "abdc0576-fae7-4b31-96dc-539b8cda095f", + "timeLimit": 420, + "allowVoteSkipMap": true, + "mediaUrlDds": "https://trackmania-prod-media-s3.cdn.ubi.com/media/image/live-api/089462af-7f9e-43cc-a561-593bbed3e1f2/dds/game.dds?timestamp=1705440002.dds", + "mediaUrlPngMedium": "https://trackmania-prod-media-s3.cdn.ubi.com/media/image/live-api/089462af-7f9e-43cc-a561-593bbed3e1f2/png/medium.png?timestamp=1705440002.png" +} +``` + +If the club or map review does not exist, the response will contain an error: + +```json +[ + "activity:error-notFound" +] +``` diff --git a/docs/live/clubs/map-review.md b/docs/live/clubs/map-review.md index d999bc9..5f58a2a 100644 --- a/docs/live/clubs/map-review.md +++ b/docs/live/clubs/map-review.md @@ -29,7 +29,7 @@ Gets a list of club map review rooms. **Remarks**: -- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png` versions are available using separate fields (see example below for reference). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. --- diff --git a/docs/live/clubs/news-by-id.md b/docs/live/clubs/news-by-id.md new file mode 100644 index 0000000..0edab54 --- /dev/null +++ b/docs/live/clubs/news-by-id.md @@ -0,0 +1,66 @@ +--- +name: Get club news by ID + +url: https://live-services.trackmania.nadeo.live +method: GET +route: /api/token/club/{clubId}/news/{newsId} + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the news belongs to + required: true + - name: newsId + type: integer + description: The ID of the news to be requested + required: true +--- + +Gets the details of a specific club news. + +--- + +**Remarks**: + +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. + +--- + +**Example request**: + +```plain +GET https://live-services.trackmania.nadeo.live/api/token/club/103034/news/1006858 +``` + +**Example response**: + +```json +{ + "creationTimestamp": 1771912390, + "mediaUrlJpgLarge": "", + "mediaUrlJpgMedium": "", + "clubName": "Fort's club", + "id": 1006858, + "name": "My news!", + "clubId": 103034, + "mediaUrl": "", + "latestEditorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "body": "This is the body of news created to test the endpoint!", + "mediaTheme": "", + "creatorAccountId": "69f31664-4252-48e0-a433-024c49caee8c", + "headline": "News for testing", + "mediaUrlJpgSmall": "", + "mediaUrlDds": "" +} +``` + +If the club or news does not exist, the response will contain an error: + +```json +[ + "activity:error-notFound" +] +``` diff --git a/docs/live/clubs/pin-club.md b/docs/live/clubs/pin-club.md new file mode 100644 index 0000000..cee96eb --- /dev/null +++ b/docs/live/clubs/pin-club.md @@ -0,0 +1,53 @@ +--- +name: Pin club + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/pin + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club to be pinned + required: true +--- + +Pins a club for the current authenticated account. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- If the club is already pinned, using this endpoint will unpin it. +- When a club is pinned, the game will display its assets while editing / playing a map in solo, and the club will be used for the club leaderboards in-game. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/131063/pin +``` + +**Example response**: + +```json +{ + "accountId": "69f31664-4252-48e0-a433-024c49caee8c", + "tag": "", + "tagClubId": 0, + "pinnedClub": 131063 +} +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` diff --git a/docs/live/clubs/room-by-id.md b/docs/live/clubs/room-by-id.md index a60a00f..45ba8cc 100644 --- a/docs/live/clubs/room-by-id.md +++ b/docs/live/clubs/room-by-id.md @@ -26,7 +26,7 @@ Gets the details of a specific club room. **Remarks**: - Club rooms connected to a dedicated server will have less information available - specifically, `maps` and `scriptSettings` will likely be empty. -- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png` versions are available using separate fields (see example below for reference). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. --- diff --git a/docs/live/clubs/room-join-link.md b/docs/live/clubs/room-join-link.md new file mode 100644 index 0000000..408d1d9 --- /dev/null +++ b/docs/live/clubs/room-join-link.md @@ -0,0 +1,69 @@ +--- +name: Get club room join link + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/room/{roomId}/join + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the room belongs to + required: true + - name: roomId + type: integer + description: The ID of the room to be requested + required: true +--- + +Gets a join link for a club room. + +--- + +**Remarks**: + +- If the requested room is inactive, using this endpoint will start it. `joinLink` will be an empty string while the room isn't ready. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/25/room/381929/join +``` + +**Example response**: + +```json +{ + "starting": false, + "joinLink": "#qjoin=fKw5ovkrSCGub82AdaoxCA" +} +``` + +If the requested room has been deactivated in the club, the response will contain an error: + +```json +[ + "roomServer:error-NoServerAvailable" +] +``` + +If the club or room does not exist, the response will contain an error: + +```json +[ + "activity:error-notFound" +] +``` + +If the requested room is private and the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` diff --git a/docs/live/clubs/room-password.md b/docs/live/clubs/room-password.md new file mode 100644 index 0000000..d4e4603 --- /dev/null +++ b/docs/live/clubs/room-password.md @@ -0,0 +1,68 @@ +--- +name: Get club room password + +url: https://live-services.trackmania.nadeo.live +method: GET +route: /api/token/club/{clubId}/room/{roomId}/get-password + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the room belongs to + required: true + - name: roomId + type: integer + description: The ID of the room to be requested + required: true +--- + +Gets the password of a club room. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). + +--- + +**Example request**: + +```plain +GET https://live-services.trackmania.nadeo.live/api/token/club/150/room/17541/get-password +``` + +**Example response**: + +```json +{ + "password": "4VJW6U" +} +``` + +If the room does not exist, it's deactivated in the club, or it's not password protected, the response will contain an error: + +```json +[ + "activity:error-notFound" +] +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the authenticated account does not have enough permissions in the club to get the password, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` diff --git a/docs/live/clubs/rooms.md b/docs/live/clubs/rooms.md index 39aa6ff..e539095 100644 --- a/docs/live/clubs/rooms.md +++ b/docs/live/clubs/rooms.md @@ -29,7 +29,7 @@ Gets a list of club rooms. **Remarks**: -- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png` versions are available using separate fields (see example below for reference). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. - This endpoint does not return all available club rooms. When excluding the `name` parameter, it returns all verified clubs' rooms - otherwise the response is limited to 200 rooms. --- diff --git a/docs/live/clubs/set-tag.md b/docs/live/clubs/set-tag.md new file mode 100644 index 0000000..a1ecf5c --- /dev/null +++ b/docs/live/clubs/set-tag.md @@ -0,0 +1,53 @@ +--- +name: Use club tag + +url: https://live-services.trackmania.nadeo.live +method: POST +route: /api/token/club/{clubId}/tag + +audience: NadeoLiveServices + +parameters: + path: + - name: clubId + type: integer + description: The ID of the club with the tag to be used + required: true +--- + +Use the club tag for the authenticated account. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- If the authenticated account is already using the club's tag, using this endpoint will remove it. +- When using a club tag, it will be displayed in-game next to the player's display name. + +--- + +**Example request**: + +```plain +POST https://live-services.trackmania.nadeo.live/api/token/club/131063/tag +``` + +**Example response**: + +```json +{ + "accountId": "69f31664-4252-48e0-a433-024c49caee8c", + "tag": "DOCS", + "tagClubId": 131063, + "pinnedClub": 0 +} +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` diff --git a/docs/live/clubs/upload-by-id.md b/docs/live/clubs/upload-by-id.md index 999f005..fc67928 100644 --- a/docs/live/clubs/upload-by-id.md +++ b/docs/live/clubs/upload-by-id.md @@ -34,9 +34,9 @@ Gets the maps, items, or skins in a specific upload activity. **Remarks**: -- The returned bucket will have one of three types : `map-upload`, `skin-upload`, or `item-upload`. These relate to club track uploads, skin uploads and item collection activities, respectively. +- See the [glossary](/glossary#club-upload-activity-types) for a list of upload types that can be returned by this endpoint. - The primary identifier for items in the returned bucket is their `itemId`. For maps this will be a `mapUid` and for skins this is a `skinID`. -- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png`/`.jpg` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. --- diff --git a/docs/live/clubs/uploads.md b/docs/live/clubs/uploads.md index 44e3576..7fc5fe7 100644 --- a/docs/live/clubs/uploads.md +++ b/docs/live/clubs/uploads.md @@ -31,8 +31,8 @@ Gets a list of club-related upload activities (where players can upload maps, sk **Remarks**: -- There are three types of upload activities you can retrieve: `map-upload`, `skin-upload`, and `item-upload`. These relate to club track uploads, skin uploads, and item collection activities, respectively. -- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png` versions are available using separate fields (see example below for reference). +- See the [glossary](/glossary#club-upload-activity-types) for a list of available upload types that can be retrieved. +- As of 2024-01-17, this endpoint's response links to `.dds` media files by default, while several scaled `.png` versions are available using separate fields (see example below for reference). This only applies for custom media files, and not for preset themes. --- diff --git a/docs/live/leaderboards/campaign-club-ranking.md b/docs/live/leaderboards/campaign-club-ranking.md new file mode 100644 index 0000000..8eb0064 --- /dev/null +++ b/docs/live/leaderboards/campaign-club-ranking.md @@ -0,0 +1,58 @@ +--- +name: Get season/campaign club ranking for player + +url: https://live-services.trackmania.nadeo.live +method: GET +route: /api/token/leaderboard/group/{groupUid}/club/{clubId} + +audience: NadeoLiveServices + +parameters: + path: + - name: groupUid + type: string + description: The ID of the group/season + required: true + - name: clubId + type: string + description: The ID of the club + required: true +--- + +Gets the authenticated account's rank in a club for the given group/season/campaign. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- The `groupUid` `"Personal_Best"` cannot be used for this endpoint because it requires a group that refers to a campaign or season. +- Unlike some other leaderboard-related endpoints that use a `groupUid` parameter, this one also supports groups/seasons that are already closed. +- The `position` field is the rank of the player within the club, instead of their rank in the season/campaign itself. + +--- + +**Example request**: + +```plain +GET https://live-services.trackmania.nadeo.live/api/token/leaderboard/group/dccdf820-6a24-4ab1-9078-58fea41282db/club/9 +``` + +**Example response**: + +```json +{ + "clubId": 9, + "position": 15, + "groupUid": "dccdf820-6a24-4ab1-9078-58fea41282db", + "sp": "24772" +} +``` + +If the `groupUid` is invalid or the authenticated account has not played the campaign/season, the response will be an empty object: + +```json +{} +``` + +An invalid `clubId` results in a response with the `position` field set to `1`. diff --git a/docs/live/leaderboards/campaign-club-top.md b/docs/live/leaderboards/campaign-club-top.md new file mode 100644 index 0000000..dc0f96e --- /dev/null +++ b/docs/live/leaderboards/campaign-club-top.md @@ -0,0 +1,107 @@ +--- +name: Get season/campaign club leaderboard + +url: https://live-services.trackmania.nadeo.live +method: GET +route: /api/token/leaderboard/group/{groupUid}/club/{clubId}/top?length={length}&offset={offset} + +audience: NadeoLiveServices + +parameters: + path: + - name: groupUid + type: string + description: The ID of the group/season + required: true + - name: clubId + type: string + description: The ID of the club + required: true + query: + - name: length + type: integer + description: The number of ranks to retrieve + default: 5 + - name: offset + type: integer + description: The number of ranks to skip + default: 0 +--- + +Gets the leaderboard of a club for the given group/season/campaign. + +--- + +**Remarks**: + +- The `groupUid` `"Personal_Best"` cannot be used for this endpoint because it requires a group that refers to a campaign or season. +- Unlike some other leaderboard-related endpoints that use a `groupUid` parameter, this one also supports groups/seasons that are already closed. +- The `position` field is the rank of the player within the club, instead of their rank in the season/campaign itself. + +--- + +**Example request**: + +```plain +GET https://live-services.trackmania.nadeo.live/api/token/leaderboard/group/dccdf820-6a24-4ab1-9078-58fea41282db/club/9/top?offset=0&length=5 +``` + +**Example response**: + +```json +{ + "top": [ + { + "accountId": "61e24c6b-8410-4998-82fe-cacc36d3ce7e", + "zoneId": "30209e41-7e13-11e8-8060-e284abfd2bc4", + "position": 1, + "zoneName": "Zuid-Holland", + "sp": "45314" + }, + { + "accountId": "421db8c7-7208-4e30-b89d-464c93a37847", + "zoneId": "3022c725-7e13-11e8-8060-e284abfd2bc4", + "position": 2, + "zoneName": "Kentucky", + "sp": "40638" + }, + { + "accountId": "02a822c2-5c84-4ec9-b15e-f43a736ce4e0", + "zoneId": "301e3b69-7e13-11e8-8060-e284abfd2bc4", + "position": 3, + "zoneName": "Victoria", + "sp": "37121" + }, + { + "accountId": "908ae383-a5d3-4bc5-ae16-ad1113d19317", + "zoneId": "301e309b-7e13-11e8-8060-e284abfd2bc4", + "position": 4, + "zoneName": "New South Wales", + "sp": "34924" + }, + { + "accountId": "dc029c0a-5188-4765-8e55-91066d425fba", + "zoneId": "301febb8-7e13-11e8-8060-e284abfd2bc4", + "position": 5, + "zoneName": "Loire-Atlantique", + "sp": "33839" + } + ], + "clubId": 9, + "groupUid": "dccdf820-6a24-4ab1-9078-58fea41282db", + "length": 588 +} +``` + +If the `clubId` is invalid, the response will contain an empty list: + +```json +{ + "top": [], + "clubId": 1239790, + "groupUid": "dccdf820-6a24-4ab1-9078-58fea41282db", + "length": 0 +} +``` + +An invalid `groupUid` results in a `200` response code and an empty response. diff --git a/docs/live/map-review/club-submitted.md b/docs/live/map-review/club-submitted.md new file mode 100644 index 0000000..27495d2 --- /dev/null +++ b/docs/live/map-review/club-submitted.md @@ -0,0 +1,112 @@ +--- +name: Get submitted maps to club map review + +url: https://live-services.trackmania.nadeo.live +method: GET +route: /api/token/club/{clubId}/map-review/{mapReviewId}/map/mine?length={length}&offset={offset}&withFeedback={withFeedback}&withMapInfo={withMapInfo} + +audience: NadeoLiveServices +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the map review activity belongs to + required: true + - name: mapReviewId + type: integer + description: The ID of the map review activity + required: true + query: + - name: length + type: integer + description: The number of maps to retrieve + required: true + - name: offset + type: integer + description: The number of maps to skip + required: true + - name: withFeedback + type: boolean + description: Whether to include detailed statistics for votes + default: false + - name: withMapInfo + type: boolean + description: Whether to include detailed info about each map + default: false +--- + +Retrieves your maps submitted to a club map review activity. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- The data returned from this endpoint is largely the same data that can be accessed through the club on the [official website](https://trackmania.com). +- If the `withFeedback` parameter is set to `false`, the `noteInfo` field in the response will be `null`. Similarly, if the `withMapInfo` parameter is set to `false`, the `map` field will be `null`. +- The relevant `mapReviewId` can be retrieved using the [club activities endpoint](/live/clubs/activities). +- This endpoint is only useful for club activities. To retrieve maps submitted to Nadeo for official game modes, use the [submitted maps endpoint](/live/map-review/submitted). + +--- + +**Example request**: + +```plain +GET https://live-services.trackmania.nadeo.live/api/token/club/103034/map-review/1008026/map/mine?offset=0&length=48&withFeedback=true&withMapInfo=true +``` + +**Example response**: + +```json +{ + "submittedMaps": [ + { + "creationTimestamp": 1772298248, + "map": { + "silverTime": 10000, + "uid": "HHFJI9m55gYcL_PxPGNTOSGPMRf", + "uploadTimestamp": 1772298221, + "downloadUrl": "https://core.trackmania.nadeo.live/storageObjects/b4d9f053-b826-41a7-b5a5-60a8df2f09c5", + "name": "My first map!", + "authorTime": 7987, + "submitter": "69f31664-4252-48e0-a433-024c49caee8c", + "mapId": "8136f63d-da93-439c-aa7c-de9f353dfcb9", + "author": "69f31664-4252-48e0-a433-024c49caee8c", + "thumbnailUrl": "https://core.trackmania.nadeo.live/storageObjects/68a7064f-da53-4aad-ba76-f85b326e0cac.jpg", + "goldTime": 9000, + "bronzeTime": 12000, + "nbLaps": 0, + "updateTimestamp": 1772298221, + "valid": true + }, + "mapUid": "HHFJI9m55gYcL_PxPGNTOSGPMRf", + "nominated": false, + "noteInfo": { + "countStar2": 0, + "countStar4": 0, + "countStar5": 0, + "countTotal": 0, + "countStar3": 0, + "countStar1": 0, + "average": 0, + "countStarMax": 0 + }, + "mapStyles": [], + "nadeoNote": 0, + "labels": [], + "feedbackCount": 0, + "latestSubmissionTimestamp": 1772298248, + "messagingOpen": false + } + ], + "itemCount": 1 +} +``` + +If the club or map review activity does not exist, the response will contain an error: + +```json +[ + "activity:error-notFound" +] +``` diff --git a/docs/live/map-review/members-submissions.md b/docs/live/map-review/members-submissions.md new file mode 100644 index 0000000..8fb7d14 --- /dev/null +++ b/docs/live/map-review/members-submissions.md @@ -0,0 +1,184 @@ +--- +name: Get member submissions to club map review + +url: https://live-services.trackmania.nadeo.live +method: GET +route: /api/token/club/{clubId}/map-review/{mapReviewId}/map?offset={offset}&length={length} + +audience: NadeoLiveServices +parameters: + path: + - name: clubId + type: integer + description: The ID of the club the map review activity belongs to + required: true + - name: mapReviewId + type: integer + description: The ID of the map review activity + required: true + query: + - name: length + type: integer + description: The number of maps to retrieve + required: true + - name: offset + type: integer + description: The number of maps to skip + required: true +--- + +Retrieves map submissions of all club members to a club map review activity. + +--- + +**Remarks**: + +- This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). +- The relevant `mapReviewId` can be retrieved using the [Get club activities endpoint](/live/clubs/activities). +- The data returned from this endpoint is largely the same data that can be accessed through the club's admin page on the [official website](https://trackmania.com). +- The response data model is similar to the [submitted maps endpoint](/live/map-review/submitted), with this endpoint including additional map information accessible to admins, including player counts data, scores, playing time, and more. + +--- + +**Example request**: + +```plain +GET https://live-services.trackmania.nadeo.live/api/token/club/103034/map-review/1008026/map?offset=0&length=10 +``` + +**Example response**: + +```json +{ + "submittedMaps": [ + { + "creationTimestamp": 1772312741, + "rejected": false, + "map": { + "silverTime": 17000, + "uid": "Sn0DFpQkzrYSpppwURh2OsyYnH7", + "uploadTimestamp": 1755390348, + "downloadUrl": "https://core.trackmania.nadeo.live/maps/3a9ac05a-0f89-4511-ba6d-fe4d11fe5128/file", + "name": "DandyMech", + "authorTime": 13540, + "submitter": "866d8ae2-11ea-4b7d-a220-f3bd0388354b", + "mapId": "3a9ac05a-0f89-4511-ba6d-fe4d11fe5128", + "author": "866d8ae2-11ea-4b7d-a220-f3bd0388354b", + "thumbnailUrl": "https://core.trackmania.nadeo.live/maps/3a9ac05a-0f89-4511-ba6d-fe4d11fe5128/thumbnail.jpg", + "goldTime": 15000, + "bronzeTime": 21000, + "nbLaps": 0, + "updateTimestamp": 1755390348, + "valid": true + }, + "difficultyScore": -1, + "mScore": 0, + "playerCountAtStart": 1, + "selected": false, + "playerFinishCount": 0, + "mapUid": "Sn0DFpQkzrYSpppwURh2OsyYnH7", + "nominated": false, + "noteInfo": { + "countStar2": 0, + "countStar4": 0, + "countStar5": 0, + "countTotal": 0, + "countStar3": 0, + "countStar1": 0, + "average": 0, + "countStarMax": 0 + }, + "mapStyles": [], + "nadeoNote": 0, + "labels": [], + "difficultyCount": 0, + "creationDate": 1772312741, + "playerCountAtEnd": 0, + "feedbackCount": 0, + "playerDidntFinishCount": 0, + "mapReviewId": 1491, + "latestSubmissionTimestamp": 1772312741, + "timePlayed": 0, + "messagingOpen": false, + "mScoreExperimental": 0 + }, + { + "creationTimestamp": 1772298248, + "rejected": false, + "map": { + "silverTime": 10000, + "uid": "HHFJI9m55gYcL_PxPGNTOSGPMRf", + "uploadTimestamp": 1772298221, + "downloadUrl": "https://core.trackmania.nadeo.live/storageObjects/b4d9f053-b826-41a7-b5a5-60a8df2f09c5", + "name": "My first map!", + "authorTime": 7987, + "submitter": "69f31664-4252-48e0-a433-024c49caee8c", + "mapId": "8136f63d-da93-439c-aa7c-de9f353dfcb9", + "author": "69f31664-4252-48e0-a433-024c49caee8c", + "thumbnailUrl": "https://core.trackmania.nadeo.live/storageObjects/68a7064f-da53-4aad-ba76-f85b326e0cac.jpg", + "goldTime": 9000, + "bronzeTime": 12000, + "nbLaps": 0, + "updateTimestamp": 1772298221, + "valid": true + }, + "difficultyScore": -1, + "mScore": -1, + "playerCountAtStart": 0, + "selected": false, + "playerFinishCount": 3, + "mapUid": "HHFJI9m55gYcL_PxPGNTOSGPMRf", + "nominated": false, + "noteInfo": { + "countStar2": 0, + "countStar4": 0, + "countStar5": 0, + "countTotal": 0, + "countStar3": 0, + "countStar1": 0, + "average": 0, + "countStarMax": 0 + }, + "mapStyles": [], + "nadeoNote": 0, + "labels": [], + "difficultyCount": 0, + "creationDate": 1772298248, + "playerCountAtEnd": 1, + "feedbackCount": 0, + "playerDidntFinishCount": 0, + "mapReviewId": 1491, + "latestSubmissionTimestamp": 1772298248, + "timePlayed": 1, + "messagingOpen": false, + "mScoreExperimental": -1 + } + ], + "flashes": [], + "itemCount": 2 +} +``` + +If the club does not exist or the authenticated account is not a member of the club, the response will contain an error: + +```json +[ + "clubMemberRole:error-notMember" +] +``` + +If the map review activity does not exist, the response will contain an error: + +```json +[ + "activity:error-notFound" +] +``` + +If the authenticated account does not have enough permissions in the club to manage map review activities, the response will contain an error: + +```json +[ + "clubMemberRole:error-notContentCreator" +] +``` diff --git a/docs/live/map-review/submitted.md b/docs/live/map-review/submitted.md index f10e125..b45be79 100644 --- a/docs/live/map-review/submitted.md +++ b/docs/live/map-review/submitted.md @@ -3,7 +3,7 @@ name: Get submitted maps url: https://live-services.trackmania.nadeo.live method: GET -route: /api/token/map/map-review/{reviewType}/submitted-map?length={length}&offset={offset}&withFeedback={withFeedback}&withMapInfo={withMapInfo} +route: /api/token/map/map-review/{reviewType}/submitted-map?length={length}&offset={offset} audience: NadeoLiveServices parameters: @@ -21,12 +21,6 @@ parameters: type: integer description: The number of maps to skip required: true - - name: withFeedback - type: boolean - description: Whether to include given feedback for each applicable map - - name: withMapInfo - type: boolean - description: Whether to include detailed info on each map --- Retrieves your maps submitted to map review. @@ -36,9 +30,9 @@ Retrieves your maps submitted to map review. **Remarks**: - This endpoint is only useful with tokens authenticated through Ubisoft user accounts (as opposed to dedicated server accounts). -- The `withFeedback` and `withMapInfo` query parameters do not seem to change what is actually returned in the response, but the game sets these to `true` when requesting maps. - The data returned from this endpoint is largely the same data that can be accessed through the player's tracks on the [official website](https://trackmania.com). - Examples of supported review types can be found in the [glossary](/glossary#map-review-type). +- This endpoint is only useful for maps submitted for official game modes. To retrieve maps submitted to club activities, use the [submitted maps to club map review endpoint](/live/map-review/club-submitted). ---