docs: add ULID notes for every applicable endpoint

docs/v1/get-achievement-of-the-week.md

@@ -79,6 +79,7 @@ if (response is NetworkResponse.Success) {
     "TrueRatio": 11,
     "Type": null,
     "Author": "StingX2",
+    "AuthorULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
     "DateCreated": "2021-10-16",
     "DateModified": "2021-10-17"
   },
@@ -98,6 +99,7 @@ if (response is NetworkResponse.Success) {
   "Unlocks": [
     {
       "User": "Agnam",
+      "ULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "RAPoints": 56120,
       "RASoftcorePoints": 1267,
       "DateAwarded": "2023-10-26T22:13:34.000000Z",
@@ -119,6 +121,7 @@ if (response is NetworkResponse.Success) {
     "points": "10",
     "trueRatio": "22",
     "author": "BigWeedSmokerMan",
+    "authorUlid": "00003EMFWR7XB8SDPEHB3K56ZQ",
     "dateCreated": "2021-08-08 17:47:46",
     "dateModified": "2021-08-09 12:20:05"
   },
@@ -130,6 +133,7 @@ if (response is NetworkResponse.Success) {
   "unlocks": [
     {
       "user": "Tirbaba2",
+      "ulid": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "rAPoints": "72",
       "rASoftcorePoints": "150",
       "dateAwarded": "2022-10-10 01:42:19",

docs/v1/get-achievement-unlocks.md

@@ -79,6 +79,7 @@ if (response is NetworkResponse.Success) {
     "Points": 4,
     "TrueRatio": 4,
     "Author": "Scott",
+    "AuthorULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
     "DateCreated": "2012-11-02 00:03:12",
     "DateModified": "2023-08-08 00:36:59",
     "Type": "progression"
@@ -97,6 +98,7 @@ if (response is NetworkResponse.Success) {
   "Unlocks": [
     {
       "User": "vipotaenko02",
+      "ULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "RAPoints": 0,
       "RASoftcorePoints": 0,
       "DateAwarded": "2023-10-27T00:19:05.000000Z",
@@ -116,6 +118,7 @@ if (response is NetworkResponse.Success) {
     "points": 4,
     "trueRatio": 4,
     "author": "Scott",
+    "authorUlid": "00003EMFWR7XB8SDPEHB3K56ZQ",
     "dateCreated": "2012-11-02 00:03:12",
     "dateModified": "2023-08-08 00:36:59",
     "type": "progression"
@@ -128,6 +131,7 @@ if (response is NetworkResponse.Success) {
   "unlocks": [
     {
       "user": "vipotaenko02",
+      "ulid": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "raPoints": 0,
       "raSoftcorePoints": 0,
       "dateAwarded": "2023-10-27T00:19:05.000000Z",

docs/v1/get-achievements-earned-between.md

@@ -20,10 +20,12 @@ A user's unlocks by a date range can be found manually via the user history:
 
 ### Query Parameters
 
+You must query the user by either their username or their ULID. Please note the username is not considered a stable value. As of 2025, users can change their usernames. Initially querying by username is a good way to fetch a ULID.
+
 | Name | Required? | Description                        |
 | :--- | :-------- | :--------------------------------- |
 | `y`  | Yes       | Your web API key.                  |
-| `u`  | Yes       | The target username.               |
+| `u`  |           | The target username or ULID.       |
 | `f`  | Yes       | Epoch timestamp. Time range start. |
 | `t`  | Yes       | Epoch timestamp. Time range end.   |
 
@@ -98,6 +100,7 @@ if (response is NetworkResponse.Success) {
     "TrueRatio": 25,
     "Type": "missable",
     "Author": "Altomar",
+    "AuthorULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
     "GameTitle": "Persona 3 Portable",
     "GameIcon": "/Images/065205.png",
     "GameID": 3164,
@@ -123,6 +126,7 @@ if (response is NetworkResponse.Success) {
     "trueRatio": 25,
     "type": null,
     "author": "pinguupinguu",
+    "authorUlid": "00003EMFWR7XB8SDPEHB3K56ZQ",
     "gameTitle": "SpongeBob SquarePants: The Movie",
     "gameIcon": "/Images/059007.png",
     "gameId": 19018,

docs/v1/get-achievements-earned-on-day.md

@@ -20,11 +20,13 @@ A user's unlocks by date can be found via the user history:
 
 ### Query Parameters
 
-| Name | Required? | Description                |
-| :--- | :-------- | :------------------------- |
-| `y`  | Yes       | Your web API key.          |
-| `u`  | Yes       | The target username.       |
-| `d`  | Yes       | Date in YYYY-MM-DD format. |
+You must query the user by either their username or their ULID. Please note the username is not considered a stable value. As of 2025, users can change their usernames. Initially querying by username is a good way to fetch a ULID.
+
+| Name | Required? | Description                  |
+| :--- | :-------- | :--------------------------- |
+| `y`  | Yes       | Your web API key.            |
+| `u`  |           | The target username or ULID. |
+| `d`  | Yes       | Date in YYYY-MM-DD format.   |
 
 ## Client Library
 
@@ -93,6 +95,7 @@ if (response is NetworkResponse.Success) {
     "Points": 5,
     "Type": null,
     "Author": "TheMysticalOne",
+    "AuthorULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
     "GameTitle": "Dragon Quest VIII: Journey of the Cursed King",
     "GameIcon": "/Images/038649.png",
     "GameID": 2721,
@@ -117,6 +120,7 @@ if (response is NetworkResponse.Success) {
     "points": 5,
     "type": null,
     "author": "pinguupinguu",
+    "authorUlid": "00003EMFWR7XB8SDPEHB3K56ZQ",
     "gameTitle": "SpongeBob SquarePants: The Movie",
     "gameIcon": "/Images/059007.png",
     "gameId": 19018,

docs/v1/get-active-claims.md

@@ -65,6 +65,7 @@ if (response is NetworkResponse.Success) {
   {
     "ID": 11246,
     "User": "WanderingHeiho",
+    "ULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
     "GameID": 26971,
     "GameTitle": "~Homebrew~ No Place To Hide",
     "GameIcon": "/Images/084916.png",
@@ -90,6 +91,7 @@ if (response is NetworkResponse.Success) {
   {
     "id": 11246,
     "user": "WanderingHeiho",
+    "ulid": "00003EMFWR7XB8SDPEHB3K56ZQ",
     "gameId": 26971,
     "gameTitle": "~Homebrew~ No Place To Hide",
     "gameIcon": "/Images/084916.png",

docs/v1/get-claims.md

@@ -68,6 +68,7 @@ if (response is NetworkResponse.Success) {
   {
     "ID": 11245,
     "User": "kmpers",
+    "ULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
     "GameID": 24541,
     "GameTitle": "GP World",
     "GameIcon": "/Images/076324.png",
@@ -93,6 +94,7 @@ if (response is NetworkResponse.Success) {
   {
     "id": 11245,
     "user": "kmpers",
+    "ulid": "00003EMFWR7XB8SDPEHB3K56ZQ",
     "gameId": 24541,
     "gameTitle": "GP World",
     "gameIcon": "/Images/076324.png",

docs/v1/get-comments.md

@@ -14,13 +14,13 @@ A call to this endpoint returns comments of a specified kind: game, achievement,
 
 ### Query Parameters
 
-| Name | Required? | Description                                                                                  |
-| :--- | :-------- | :------------------------------------------------------------------------------------------- |
-| `y`  | Yes       | Your web API key.                                                                            |
-| `i`  | Yes       | The target game or achievement ID (if type is 1 or 2). The target username (if type is 3).   |
-| `t`  | Sometimes | The target comment kind: 1 (game), 2 (achievement), or 3 (user). Required if type is 1 or 2. |
-| `c`  |           | Count, number of records to return (default: 100, max: 500).                                 |
-| `o`  |           | Offset, number of entries to skip (default: 0).                                              |
+| Name | Required? | Description                                                                                             |
+| :--- | :-------- | :------------------------------------------------------------------------------------------------------ |
+| `y`  | Yes       | Your web API key.                                                                                       |
+| `i`  | Yes       | The target game or achievement ID (if type is 1 or 2). The target username or user ULID (if type is 3). |
+| `t`  | Sometimes | The target comment kind: 1 (game), 2 (achievement), or 3 (user). Required if type is 1 or 2.            |
+| `c`  |           | Count, number of records to return (default: 100, max: 500).                                            |
+| `o`  |           | Offset, number of entries to skip (default: 0).                                                         |
 
 ## Client Library
 
@@ -102,6 +102,7 @@ if (response is NetworkResponse.Success) {
     "Results": [
         {
             "User": "PlayTester",
+            "ULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
             "Submitted": "2024-07-31T11:22:23.000000Z",
             "CommentText": "Comment 1"
         },

docs/v1/get-game-extended.md

@@ -106,6 +106,7 @@ if (response is NetworkResponse.Success) {
       "Points": 3,
       "TrueRatio": 3,
       "Author": "Scott",
+      "AuthorULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "DateModified": "2023-08-08 00:36:59",
       "DateCreated": "2012-11-02 00:03:12",
       "BadgeName": "250336",
@@ -154,6 +155,7 @@ if (response is NetworkResponse.Success) {
       "points": 1,
       "trueRatio": 1,
       "author": "Boldewin",
+      "authorUlid": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "dateModified": "2019-08-01 19:03:46",
       "dateCreated": "2019-07-31 18:49:57",
       "badgeName": "85541",

docs/v1/get-game-info-and-user-progress.md

@@ -14,10 +14,12 @@ A call to this endpoint will retrieve extended metadata about a game, in additio
 
 ### Query Parameters
 
+You must query the user by either their username or their ULID. Please note the username is not considered a stable value. As of 2025, users can change their usernames. Initially querying by username is a good way to fetch a ULID.
+
 | Name | Required? | Description                                                        |
 | :--- | :-------- | :----------------------------------------------------------------- |
 | `y`  | Yes       | Your web API key.                                                  |
-| `u`  | Yes       | The target username.                                               |
+| `u`  |           | The target username or ULID.                                       |
 | `g`  | Yes       | The target game ID.                                                |
 | `a`  |           | Set to "1" if user award metadata should be included (default: 0). |
 
@@ -108,6 +110,7 @@ if (response is NetworkResponse.Success) {
       "Points": 3,
       "TrueRatio": 3,
       "Author": "Scott",
+      "AuthorULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "DateModified": "2023-08-08 00:36:59",
       "DateCreated": "2012-11-02 00:03:12",
       "BadgeName": "250336",
@@ -162,6 +165,7 @@ if (response is NetworkResponse.Success) {
       "points": 1,
       "trueRatio": 1,
       "author": "Boldewin",
+      "authorUlid": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "dateModified": "2019-08-01 19:03:46",
       "dateCreated": "2019-07-31 18:49:57",
       "badgeName": "85541",

docs/v1/get-game-leaderboards.md

@@ -71,6 +71,7 @@ if (response is NetworkResponse.Success) {
       "Format": "VALUE",
       "TopEntry": {
         "User": "vani11a",
+        "ULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
         "Score": "390490",
         "FormattedScore": "390,490"
       }

docs/v1/get-game-rank-and-score.md

@@ -82,6 +82,7 @@ How entities are ordered in this response should be noted. For `latest-masters`,
 [
   {
     "User": "Arekdias",
+    "ULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
     "NumAchievements": 15,
     "TotalScore": 219,
     "LastAward": "2023-06-07 14:43:18"
@@ -94,6 +95,7 @@ How entities are ordered in this response should be noted. For `latest-masters`,
 [
   {
     "user": "BruceLee1255",
+    "ulid": "00003EMFWR7XB8SDPEHB3K56ZQ",
     "totalScore": 0,
     "lastAward": "2019-07-30 23:19:43",
     "rank": 27

docs/v1/get-leaderboard-entries.md

@@ -66,6 +66,7 @@ if (response is NetworkResponse.Success) {
     {
       "Rank": 1,
       "User": "vani11a",
+      "ULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "Score": 390490,
       "FormattedScore": "390,490",
       "DateSubmitted": "2024-07-25T15:51:00+00:00"

docs/v1/get-recent-game-awards.md

@@ -80,6 +80,7 @@ if (response is NetworkResponse.Success) {
   "Results": [
     {
       "User": "renanbrj",
+      "ULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "AwardKind": "mastered",
       "AwardDate": "2022-01-01T23:48:04+00:00",
       "GameID": 14284,
@@ -99,6 +100,7 @@ if (response is NetworkResponse.Success) {
   "results": [
     {
       "user": "renanbrj",
+      "ulid": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "awardKind": "mastered",
       "awardDate": "2022-01-01T23:48:04+00:00",
       "gameId": 14_284,

docs/v1/get-ticket-data/get-developer-ticket-stats.md

@@ -14,10 +14,13 @@ A call to `API_GetTicketData` in this manner will retrieve ticket stats for a de
 
 ### Query Parameters
 
+You must query the developer by either their username or their ULID. Please note the username is not considered a stable value. As of 2025, users can change their usernames. Initially querying by username is a good way to fetch a ULID.
+
 | Name | Required? | Description                      |
 | :--- | :-------- | :------------------------------- |
 | `y`  | Yes       | Your web API key.                |
-| `u`  | Yes       | The target developer's username. |
+| `u`  |           | The target developer's username. |
+| `i`  |           | The target developer's ULID.     |
 
 ## Client Library
 
@@ -68,6 +71,7 @@ if (response is NetworkResponse.Success) {
 ```json [HTTP Response]
 {
   "User": "MockUser",
+  "ULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
   "Open": 0,
   "Closed": 17,
   "Resolved": 27,
@@ -79,6 +83,7 @@ if (response is NetworkResponse.Success) {
 ```json [NodeJS]
 {
   "user": "MockUser",
+  "ulid": "00003EMFWR7XB8SDPEHB3K56ZQ",
   "open": 0,
   "closed": 17,
   "resolved": 27,

docs/v1/get-ticket-data/get-most-recent-tickets.md

@@ -78,6 +78,7 @@ if (response is NetworkResponse.Success) {
       "Points": 0,
       "BadgeName": "361407",
       "AchievementAuthor": "WCopeland",
+      "AchievementAuthorULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "GameID": 24453,
       "ConsoleName": "Mega Drive",
       "GameTitle": "~Homebrew~ Mega Man: The Sequel Wars - Episode Red",
@@ -87,8 +88,10 @@ if (response is NetworkResponse.Success) {
       "Hardcore": 1,
       "ReportNotes": "asdfasdfasdfasdf\nRetroAchievements Hash: bff0eb90c2006edade14063d4a2d13cf\nEmulator: RALibRetro (123123)\nEmulator Version: 123",
       "ReportedBy": "WCopeland",
+      "ReportedByULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "ResolvedAt": null,
       "ResolvedBy": null,
+      "ResolvedByULID": null,
       "ReportState": 1,
       "ReportStateDescription": "Open",
       "ReportTypeDescription": "Did not trigger"
@@ -110,6 +113,7 @@ if (response is NetworkResponse.Success) {
       "points": 5,
       "badgeName": "316108",
       "achievementAuthor": "TeddyWestside",
+      "achievementAuthorUlid": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "gameId": 19144,
       "consoleName": "PlayStation 2",
       "gameTitle": "X-Men Legends",
@@ -119,8 +123,10 @@ if (response is NetworkResponse.Success) {
       "hardcore": true,
       "reportNotes": "mockReportNotes",
       "reportedBy": "ManyHours",
+      "reportedByUlid": "00003EMFWR7XB8SDPEHB3K56ZQ",
       "resolvedAt": null,
       "resolvedBy": null,
+      "resolvedByUlid": null,
       "reportState": 1,
       "reportStateDescription": "Open",
       "reportTypeDescription": "Did not trigger"

docs/v1/get-ticket-data/get-ticket-by-id.md

@@ -73,6 +73,7 @@ if (response is NetworkResponse.Success) {
   "Points": 3,
   "BadgeName": "309094",
   "AchievementAuthor": "tuteur51",
+  "AchievementAuthorULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
   "GameID": 2816,
   "ConsoleName": "Game Boy Advance",
   "GameTitle": "Pokémon Mystery Dungeon: Red Rescue Team",
@@ -83,8 +84,10 @@ if (response is NetworkResponse.Success) {
   "Hardcore": null,
   "ReportNotes": "Right before going to Thunderwave Cave, all three of these triggered at the same time.<br/>MD5: 9837da1fdfe900c52f2109d9718d4e85",
   "ReportedBy": "ThatOneEnderMan",
+  "ReportedByULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
   "ResolvedAt": "2018-04-16 08:03:31",
   "ResolvedBy": "tuteur51",
+  "ResolvedByULID": "00003EMFWR7XB8SDPEHB3K56ZQ",
   "ReportStateDescription": "Resolved",
   "ReportTypeDescription": "Triggered at the wrong time",
   "URL": "https://retroachievements.org/ticket/12345"
@@ -100,6 +103,7 @@ if (response is NetworkResponse.Success) {
   "points": 3,
   "badgeName": "309094",
   "achievementAuthor": "tuteur51",
+  "achievementAuthorUlid": "00003EMFWR7XB8SDPEHB3K56ZQ",
   "gameId": 2816,
   "consoleName": "Game Boy Advance",
   "gameTitle": "Pokemon Mystery Dungeon: Red Rescue Team",
@@ -110,8 +114,10 @@ if (response is NetworkResponse.Success) {
   "hardcore": null,
   "reportNotes": "Right before going to Thunderwave Cave, all three of these triggered at the same time.<br/>MD5: 9837da1fdfe900c52f2109d9718d4e85",
   "reportedBy": "ThatOneEnderMan",
+  "reportedByUlid": "00003EMFWR7XB8SDPEHB3K56ZQ",
   "resolvedAt": "2018-04-16 08:03:31",
   "resolvedBy": "tuteur51",
+  "resolvedByUlid": "00003EMFWR7XB8SDPEHB3K56ZQ",
   "reportStateDescription": "Resolved",
   "reportTypeDescription": "Triggered at the wrong time",
   "url": "https://retroachievements.org/ticketmanager.php?i=12345"