All examples except user notifications

docs/forums.md

@@ -7,7 +7,7 @@ Endpoints related to the forums.
 
 **Request**
 
-`ajax.php?action=forum&type=main`
+`ajax.php?action=forum`
 
 
 **Response**

docs/index.md

@@ -1,18 +1,23 @@
-The JSON API provides an easily parseable interface to BioTorrents.de.
-Below is the list of information available, then arguments that can be passed to it, and the format of the results.
+The JSON API provides an easily parseable interface to [BioTorrents.de](https://biotorrents.de).
+Please use the navigation menu to find lists of endpoints, their arguments, and example responses.
 
 You must be logged in to use the API.
 This is done by sending a POST request to
-`https://biotorrents.de/login.php` with `username` and `password`
+
+`https://biotorrents.de/login.php`
+
+with `username` and `password`
 and storing a cookie to be used to access the rest of the API.
 
 
 # Introduction
 
 All request URLs are in the form
-`ajax.php?action=<action>`.
+
+`ajax.php?action=<action>`
 
 All the JSON returned is in the form
+
 ```json
 {
   "status": "success",
@@ -54,23 +59,23 @@ Please get it touch if you'd like me to list your project below.
 
 ## Rate limit
 
-The JSON API is rate-limited to one request every ten seconds.
-This limit doesn't apply to the Donor class.
+The API is rate-limited to one request every ten seconds.
+This limit doesn't apply to users in the Donor class.
 
 
 ## Under construction
 
 Some endpoints aren't working correctly right now:
 
-- artist
-- preview
+- `artist`
+- `preview`
 
 [Oppaitime Gazelle](https://git.oppaiti.me/Oppaitime/Gazelle)
 also contains other undocumented endpoints:
 
-- get_friends
-- news_ajax
-- send_recommendation
+- `get_friends`
+- `news_ajax`
+- `send_recommendation`
 
 
 # Not implemented

docs/meta.md

@@ -1,6 +1,6 @@
 # Meta
 
-Endpoints related to BioTorrents.de itself.
+Endpoints related to [BioTorrents.de](https://biotorrents.de) itself.
 
 
 ## Index
@@ -162,7 +162,7 @@ Fetch the recent news and blogs.
 
 ## Wiki
 
-Note that either `id` or `name` is required.
+Either `id` or `name` is required.
 
 **Request**
 

docs/torrents.md

@@ -163,8 +163,8 @@ Endpoints related to torrents.
 
 ## Browse (search)
 
-Note that BioTorrents.de still uses Oppaitime metadata under the hood.
-These docs are adapted from What.CD, an older and different distribution.
+Note that [BioTorrents.de](https://biotorrents.de) still uses Oppaitime metadata behind the scenes.
+These docs are also adapted from What.CD, an older and different distribution.
 The advanced search options are certain to change in the future.
 
 
@@ -372,7 +372,7 @@ Fetch comments from torrent pages.
 
 Under construction as of 2020-11-24.
 Currently not returning the artist's torrent groups.
-Please see the below reponse for details.
+Please see the response below for details.
 
 
 **Request**
@@ -433,19 +433,268 @@ Fetch the Top 10 torrents, tags, or users.
 **Response**
 
 ```json
-
+{
+    "status": "success",
+    "response": [
+        {
+            "caption": "Most Active Torrents Uploaded in the Past Day",
+            "tag": "day",
+            "limit": 10,
+            "results": [
+                {
+                    "torrentId": 67,
+                    "groupId": 57,
+                    "author": "Production Sanborn LLC",
+                    "groupName": "Massachusetts 1:5,000 Color Ortho Imagery",
+                    "groupCategory": 9,
+                    "groupYear": 2005,
+                    "platform": "Other",
+                    "tags": [
+                        "data.science",
+                        "one.shot",
+                        "true.color",
+                        "massachusetts",
+                        "geography"
+                    ],
+                    "snatched": 0,
+                    "seeders": 2,
+                    "leechers": 0,
+                    "data": 0,
+                    "size": 24759011328,
+                    "picture": ""
+                },
+                {
+                    "torrentId": 18,
+                    "groupId": 18,
+                    # etc.
+                },
+                # etc.
+            ]
+        },
+        {
+            "caption": "Most Active Torrents Uploaded in the Past Week",
+            "tag": "week",
+            "limit": 10,
+            "results": [
+                {
+                    "torrentId": 30,
+                    "groupId": 15,
+                    # etc.
+                },
+                {
+                    "torrentId": 32,
+                    "groupId": 27,
+                    # etc.
+                },
+                # etc.
+            ]
+        },
+        {
+            "caption": "Most Active Torrents of All Time",
+            "tag": "overall",
+            "limit": 10,
+            "results": [
+                {
+                    "torrentId": 1,
+                    "groupId": 1,
+                    # etc.
+                },
+                {
+                    "torrentId": 25,
+                    "groupId": 25,
+                    # etc.
+                },
+                # etc.
+            ]
+        },
+        {
+            "caption": "Most Snatched Torrents",
+            "tag": "snatched",
+            "limit": 10,
+            "results": [
+                {
+                    "torrentId": 40,
+                    "groupId": 32,
+                    # etc.
+                },
+                {
+                    "torrentId": 43,
+                    "groupId": 34,
+                    # etc.
+                },
+                # etc.
+            ]
+        },
+        {
+            "caption": "Most Data Transferred Torrents",
+            "tag": "data",
+            "limit": 10,
+            "results": [
+                {
+                    "torrentId": 28,
+                    "groupId": 17,
+                    # etc.
+                },
+                {
+                    "torrentId": 10,
+                    "groupId": 10,
+                    # etc.
+                },
+                # etc.
+            ]
+        },
+        {
+            "caption": "Best Seeded Torrents",
+            "tag": "seeded",
+            "limit": 10,
+            "results": [
+                {
+                    "torrentId": 50,
+                    "groupId": 40,
+                    # etc.
+                },
+                {
+                    "torrentId": 48,
+                    "groupId": 38,
+                    # etc.
+                },
+                # etc.
+            ]
+        }
+    ]
+}
 ```
 
 
 ### Tags
 
 ```json
-
+{
+    "status": "success",
+    "response": [
+        {
+            "caption": "Most Used Torrent Tags",
+            "tag": "ut",
+            "limit": 10,
+            "results": [
+                {
+                    "name": "one.shot",
+                    "uses": 24
+                },
+                {
+                    "name": "humans",
+                    "uses": 22
+                },
+                {
+                    "name": "data.science",
+                    "uses": 20
+                },
+                # etc.
+            ]
+        },
+        {
+            "caption": "Most Used Request Tags",
+            "tag": "ur",
+            "limit": 10,
+            "results": [
+                {
+                    "name": "coding",
+                    "uses": 2
+                },
+                {
+                    "name": "biochemistry",
+                    "uses": 2
+                },
+                {
+                    "name": "plants",
+                    "uses": 1
+                },
+                # etc.
+            ]
+        }
+    ]
+}
 ```
 
 
 ### Users
 
-```json
+Usernames are masked to `null` in the output unless you have moderator permissions.
 
+```json
+{
+    "status": "success",
+    "response": [
+        {
+            "caption": "Uploaders",
+            "tag": "ul",
+            "limit": 10,
+            "results": [
+                {
+                    "id": 28,
+                    "username": "seedbox",
+                    "uploaded": 100918879562,
+                    "upSpeed": 4893.906,
+                    "downloaded": 12327881516,
+                    "downSpeed": 600.9437,
+                    "numUploads": 0,
+                    "joinDate": "2020-04-01 15:50:04"
+                },
+                # etc.
+            ]
+        },
+        {
+            "caption": "Downloaders",
+            "tag": "dl",
+            "limit": 10,
+            "results": [
+                {
+                    "id": 28,
+                    "username": "seedbox",
+                    # etc.
+                },
+                # etc.
+            ]
+        },
+        {
+            "caption": "Torrents Uploaded",
+            "tag": "numul",
+            "limit": 10,
+            "results": [
+                {
+                    "id": 28,
+                    "username": "seedbox",
+                    # etc.
+                },
+                # etc.
+            ]
+        },
+        {
+            "caption": "Fastest Uploaders",
+            "tag": "uls",
+            "limit": 10,
+            "results": [
+                {
+                    "id": 28,
+                    "username": "seedbox",
+                    # etc.
+                },
+                # etc.
+            ]
+        },
+        {
+            "caption": "Fastest Downloaders",
+            "tag": "dls",
+            "limit": 10,
+            "results": [
+                {
+                    "id": 28,
+                    "username": "seedbox",
+                    # etc.
+                },
+                # etc.
+            ]
+        }
+    ]
+}
 ```

docs/users.md

@@ -18,7 +18,62 @@ If you're viewing your own account, `personal->passkey` will be shown.
 **Response**
 
 ```json
-
+{
+    "status": "success",
+    "response": {
+        "username": "eva",
+        "avatar": "https://ptpimg.me/1x1h48.png",
+        "isFriend": false,
+        "profileText": "",
+        "stats": {
+            "joinedDate": "2020-03-08 14:27:59",
+            "lastAccess": "2020-11-24 15:25:17",
+            "uploaded": 2192870833,
+            "downloaded": 1244283888,
+            "ratio": 1.76235,
+            "requiredRatio": 0
+        },
+        "ranks": {
+            "uploaded": 0,
+            "downloaded": 2,
+            "uploads": 0,
+            "requests": 0,
+            "bounty": 0,
+            "posts": 2,
+            "artists": 0,
+            "overall": 0
+        },
+        "personal": {
+            "class": "Donor",
+            "paranoia": 0,
+            "paranoiaText": "Off",
+            "donor": false,
+            "warned": false,
+            "enabled": true,
+            "passkey": ""
+        },
+        "community": {
+            "posts": 4,
+            "torrentComments": 0,
+            "artistComments": 0,
+            "collageComments": 0,
+            "requestComments": 0,
+            "collagesStarted": 1,
+            "collagesContrib": 1,
+            "requestsFilled": 0,
+            "bountyEarned": 0,
+            "requestsVoted": 0,
+            "bountySpent": 0,
+            "uploaded": 0,
+            "groups": 0,
+            "seeding": 0,
+            "leeching": 0,
+            "snatched": 7,
+            "invited": 0,
+            "artistsAdded": 0
+        }
+    }
+}
 ```
 
 
@@ -36,7 +91,35 @@ If you're viewing your own account, `personal->passkey` will be shown.
 **Response**
 
 ```json
-
+{
+    "status": "success",
+    "response": {
+        "currentPage": 1,
+        "pages": 1,
+        "results": [
+            {
+                "userId": 42,
+                "username": "hedomedo",
+                "donor": false,
+                "warned": false,
+                "enabled": true,
+                "class": "User",
+                "avatar": ""
+            },
+            {
+                "userId": 2,
+                "username": "me",
+                # etc.
+            },
+            {
+                "userId": 16,
+                "username": "Medicus",
+                # etc.
+            },
+            # etc.
+        ]
+    }
+}
 ```
 
 
@@ -52,28 +135,89 @@ If you're viewing your own account, `personal->passkey` will be shown.
 **Response**
 
 ```json
-
+{
+    "status": "success",
+    "response": {
+        "leeching": 0,
+        "seeding": "60",
+        "snatched": "3",
+        "usnatched": false,
+        "downloaded": false,
+        "udownloaded": false,
+        "seedingperc": 100
+    }
+}
 ```
 
 
 ## Recents (torrents)
 
 This endpoint circumvents the "upload anonymously" feature.
+Various features of the response will likely change in the future.
 
 
 **Request**
 
 `ajax.php?action=user_recents`
 
-`&userid=` id of user (required)
+`&userid=` — id of user (required)
 
-`&limit=` how many recent torrents to fetch
+`&limit=` — how many recent torrents to fetch
 
 
 **Response**
 
 ```json
-
+{
+    "status": "success",
+    "response": {
+        "snatches": [
+            {
+                "ID": 41,
+                "Name": "Enzymatic synthesis of psilocybin",
+                "WikiImage": "https://mycocosm.jgi.doe.gov/public/Psiser1/P+serbica+2.png",
+                "artists": [
+                    [
+                        {
+                            "id": 58,
+                            "name": "Dirk Hoffmeister"
+                        },
+                        {
+                            "id": 57,
+                            "name": "Felix Blei"
+                        },
+                        {
+                            "id": 56,
+                            "name": "Janis Fricke"
+                        }
+                    ]
+                ]
+            },
+            {
+                "ID": 23,
+                "Name": "uBiome kombucha data",
+                "WikiImage": "https://kombucha-genomics.github.io/photos/pexels-photo-130947.jpeg",
+                # etc.
+            },
+            # etc.
+        ],
+        "uploads": [
+            {
+                "ID": 40,
+                "Name": "COVID-19 Genomics UK Consortium: 2020-04-24",
+                "WikiImage": "https://www.cogconsortium.uk/wp-content/uploads/2020/04/Screenshot-2020-04-27-at-15.40.51-1536x756.png",
+                # etc.
+            },
+            {
+                "ID": 16,
+                "Name": "Infinite Discovery Machine v3",
+                "WikiImage": "https://binomicalabs.org/wp-content/uploads/2017/04/The-Infinite-Discovery-Machine-Binomica-Labs.jpg",
+                # etc.
+            },
+            # etc.
+        ]
+    }
+}
 ```
 
 
@@ -83,13 +227,47 @@ This endpoint circumvents the "upload anonymously" feature.
 
 `ajax.php?action=userhistory&type=posts`
 
-`&userid=` id of user (required)
+`&userid=` — id of user (required)
 
 
 **Response**
 
 ```json
-
+{
+    "status": "success",
+    "response": {
+        "currentPage": 1,
+        "pages": 2,
+        "threads": [
+            {
+                "postId": 52,
+                "topicId": 2,
+                "threadTitle": "Report broken site features",
+                "lastPostId": 52,
+                "lastRead": 0,
+                "locked": true,
+                "sticky": false,
+                "addedTime": "2020-11-19 03:17:36",
+                "body": "HTML",
+                "bbbody": "BBcode",
+                "editedUserId": 1,
+                "editedTime": "2020-11-19 16:22:48",
+                "editedUsername": "ohm"
+            },
+            {
+                "postId": 49,
+                "topicId": 36,
+                # etc.
+            },
+            {
+                "postId": 48,
+                "topicId": 35,
+                # etc.
+            },
+            # etc.
+        ]
+    }
+}
 ```
 
 
@@ -97,8 +275,12 @@ This endpoint circumvents the "upload anonymously" feature.
 
 Endpoints that only fetch info about your own account.
 
+
 ## Inbox
 
+The current example isn't from the [BioTorrents.de](https://biotorrents.de) database.
+
+
 **Request**
 
 `ajax.php?action=inbox`
@@ -116,13 +298,39 @@ Endpoints that only fetch info about your own account.
 
 **Response**
 
-```
-
+```json
+{
+    "status": "success",
+    "response": {
+        "currentPage": 1,
+        "pages": 3,
+        "messages": [
+            {
+                "convId": 3421929,
+                "subject": "1 of your torrents has been deleted for inactivity",
+                "unread": false,
+                "sticky": false,
+                "forwardedId": 0,
+                "forwardedName": "",
+                "senderId": 0,
+                "username": "",
+                "donor": false,
+                "warned": false,
+                "enabled": true,
+                "date": "2012-06-12 00:54:01"
+            },
+            # etc.
+        ]
+    }
+}
 ```
 
 
 ## Conversation 
 
+The current example isn't from the [BioTorrents.de](https://biotorrents.de) database.
+
+
 **Request**
 
 `ajax.php?action=inbox&type=viewconv`
@@ -133,7 +341,25 @@ Endpoints that only fetch info about your own account.
 **Response**
 
 ```json
-
+{
+    "status": "success",
+    "response": {
+        "convId": 3421929,
+        "subject": "1 of your torrents has been deleted for inactivity",
+        "sticky": false,
+        "messages": [
+            {
+                "messageId": 4507261,
+                "senderId": 0,
+                "senderName": "System",
+                "sentDate": "2012-06-12 00:54:01",
+                "bbBody": "BBcode",
+                "body": "HTML"
+            },
+            # etc.
+        ]
+    }
+}
 ```
 
 ## Bookmarks
@@ -153,13 +379,64 @@ Fetch bookmarked torrents or artists.
 **Response**
 
 ```json
-
+{
+    "status": "success",
+    "response": {
+        "bookmarks": [
+            {
+                "id": 33,
+                "name": "CoronaWhy: Collaborative sharing of datasets by members of the CoronaWhy group",
+                "year": 2020,
+                "accession": "",
+                "tagList": "machine_learning data_science epidemiology germany natural_language",
+                "vanityHouse": false,
+                "picture": "https://i.imgur.com/kt0MsEg.jpg",
+                "torrents": [
+                    {
+                        "id": 41,
+                        "groupId": 33,
+                        "platform": "Literature",
+                        "fileCount": 1,
+                        "freeTorrent": false,
+                        "size": 13703876874,
+                        "leechers": 0,
+                        "seeders": 4,
+                        "snatched": 2,
+                        "time": "2020-04-18 22:54:03",
+                        "hasFile": 41
+                    }
+                ]
+            },
+            {
+                "id": 48,
+                "name": "Applied Proteogenomics OrganizationaL Learning and Outcomes (APOLLO) Image Data",
+                # etc.
+            },
+            # etc.
+        ]
+    }
+}
 ```
 
 ### Artists
 
 ```json
-
+{
+    "status": "success",
+    "response": {
+        "artists": [
+            {
+                "artistId": 136,
+                "artistName": "Marco Cantoni"
+            },
+            {
+                "artistId": 124,
+                "artistName": "Bruce Vendt"
+            },
+            # etc.
+        ]
+    }
+}
 ```
 
 
@@ -175,7 +452,7 @@ Fetch bookmarked torrents or artists.
 **Response**
 
 ```json
-todo
+
 ```
 
 
@@ -189,7 +466,7 @@ todo
 **Response**
 
 ```json
-todo
+
 ```