First commit

docs/forums.md

@@ -0,0 +1,92 @@
+# Forums
+
+Endpoints related to the forums.
+
+
+## Category view
+
+**Request**
+
+`ajax.php?action=forum&type=main`
+
+
+**Response**
+
+```json
+
+```
+
+
+## Forum view
+
+**Request**
+
+`ajax.php?action=forum&type=viewforum`
+
+`&forumid=` — id of the forum to display (required)
+
+`&page=` — the page to display (default: `1`)
+
+
+**Response**
+
+```json
+
+```
+
+
+## Thread view 
+
+**Request**
+
+`ajax.php?action=forum&type=viewthread`
+
+`&threadid=` — id of the thread to display (required)
+
+`&postid=` — response will be the page including the post with this id
+
+`&page=` — page to display (default: `1`)
+
+`&updatelastread=` — set to `1` to not update the last read id (default: `0`)
+
+
+**Response**
+
+```json
+
+```
+
+
+## Subscriptions
+
+**Request**
+
+`ajax.php?action=subscriptions`
+
+`&showunread=` — `1` to show only unread, `0` for all subscriptions (default: `1`)
+
+
+**Response**
+
+```json
+
+```
+
+
+## Raw BBcode
+
+Fetch a post's unrendered content.
+
+
+**Request**
+
+`ajax.php?action=raw_bbcode`
+
+`&postid=` — post id to display (required)
+
+
+**Response**
+
+```json
+
+```

docs/index.md

@@ -0,0 +1,153 @@
+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.
+
+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`
+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>`.
+
+All the JSON returned is in the form
+```json
+{
+    "status": "success",
+    "response": {
+	// data
+    }
+}
+```
+
+If the request is invalid, or a problem occurs, the `status` will be `failure`.
+In this case the value of `response` is `undefined`.
+
+
+# Libraries
+
+These are the current public projects listed on the
+[What.CD Gazelle wiki](https://github.com/WhatCD/Gazelle/wiki/JSON-API-Documentation).
+Questions about the API can be answered in `#development` on
+[Slack](https://join.slack.com/t/biotorrents/shared_invite/enQtODY2Mzg5NzI2OTk5LWQ0NmRlYzZmYTYwMzc3MjJlMzc4ZGJkNzQ1OWE4NDAxYTc3ZTdjY2NkOGRjNDA5MDAxZTA1Y2Y3M2MzMzIwZGY).
+
+Please get it touch if you'd like me to list your project below.
+
+
+| Language	| GitHub |
+| :--		| :-- |
+| C#		| [frankston/WhatAPI](https://github.com/frankston/WhatAPI) |
+| Go		| [kdvh/whatapi](https://github.com/kdvh/whatapi) |
+| JavaScript	| [deoxxa/whatcd](https://github.com/deoxxa/whatcd) |
+| Java		| [Gwindow/WhatAPI](https://github.com/Gwindow/WhatAPI) |
+| PHP		| [Jleagle/gazelle-api-client](https://github.com/Jleagle/gazelle-api-client) |
+| Python	| [isaaczafuta/whatapi](https://github.com/isaaczafuta/whatapi) |
+| Ruby		| [chasemgray/RubyGazelle](https://github.com/chasemgray/RubyGazelle) |
+
+
+# Caveats
+
+**Abusing or using this API for malicious purposes is a bannable offense and will not be taken lightly.**
+
+
+## Rate limit
+
+The JSON API is rate-limited to one request every ten seconds.
+This limit doesn't apply to the Donor class.
+
+
+## Under construction
+
+Some endpoints aren't working correctly right now:
+
+- artist
+- preview
+
+[Oppaitime Gazelle](https://git.oppaiti.me/Oppaitime/Gazelle)
+also contains other undocumented endpoints:
+
+- get_friends
+- news_ajax
+- send_recommendation
+
+
+# Not implemented
+
+## Similar artists
+
+**Request**
+
+`ajax.php?action=similar_artists`
+
+`&id=` — id of artist (required)
+
+`&limit=` — maximum number of results to return (fewer might be returned)
+
+
+**Response**
+
+```json
+
+```
+
+
+## Better
+
+Fetch various better.php info.
+
+
+**Request**
+
+`ajax.php?action=better`
+
+
+**Response**
+
+```json
+
+```
+
+
+
+## Torrent info
+
+**Request**
+
+`ajax.php?action=torrent_info`
+
+
+**Response**
+
+```json
+
+```
+
+
+## Check private
+
+**Request**
+
+`ajax.php?action=checkprivate`
+
+
+**Response**
+
+```json
+
+```
+
+
+## Vote favorite
+
+**Request**
+
+`ajax.php?action=votefavorite`
+
+
+**Response**
+
+```json
+
+```

docs/meta.md

@@ -0,0 +1,86 @@
+# Meta
+
+Endpoints related to BioTorrents.de itself.
+
+
+## Index
+
+Fetch basic site info from the homepage,
+e.g., if there's a new announcement.
+
+
+**Request**
+
+`ajax.php?action=index`
+
+
+**Response**
+
+```json
+
+```
+
+
+## Stats
+
+Fetch the homepage sidebar info.
+
+
+**Request**
+
+`ajax.php?action=stats`
+
+
+**Response**
+
+```json
+
+```
+
+
+## Announcements 
+
+**Request**
+
+`ajax.php?action=announcements`
+
+
+**Response**
+
+```json
+
+```
+
+
+## Load average 
+
+**Request**
+
+`ajax.php?action=loadavg`
+
+
+**Response**
+
+```json
+
+```
+
+
+## Wiki
+
+Note that either `id` or `name` is required.
+
+**Request**
+
+`ajax.php?action=wiki`
+
+`&id=` — page id to display (required)
+
+`&name=` — page alias to display
+
+
+**Response**
+
+```json
+
+```

docs/requests.md

@@ -0,0 +1,50 @@
+# Requests
+
+Endpoints related to torrent requests.
+
+
+## Request
+
+**Request**
+
+`ajax.php?action=request`
+
+`&id=` — request id (required)
+
+`&page=` — page of the comments to display (default: last page)
+
+
+**Response**
+
+```json
+
+```
+
+
+## Search
+
+If no arguments are specified then the most recent requests are shown.
+
+
+**Request**
+
+`ajax.php?action=requests`
+
+`&page=` — page to display (default: `1`)
+
+`&search=` — search term
+
+`&show_filled=` — include filled requests in results `true` or `false` (default: `false`)
+
+`&tag=` — tags to search by (comma separated)
+
+`&tags_type=` — `0` for any, `1` for match all
+
+`filter_cat[]`, `releases[]`, `bitrates[]`, `formats[]`, `media[]` — as used on requests.php
+
+
+**Response**
+
+```json
+
+```

docs/torrents.md

@@ -0,0 +1,156 @@
+# Torrents
+
+Endpoints related to torrents.
+
+
+## Torrent
+
+**Request**
+
+`ajax.php?action=torrent`
+
+`&id=` — torrent's id (required)
+
+`&hash=` — torrent's hash (must be uppercase)
+
+
+**Response**
+
+```json
+
+```
+
+
+## Torrent group
+
+**Request**
+
+`ajax.php?action=torrentgroup`
+
+`&id=` — torrent's group id (required)
+
+`&hash=` — hash of a torrent in the torrent group (must be uppercase)
+
+
+**Response**
+
+```json
+
+```
+
+
+## Browse (search)
+
+Note that BioTorrents.de still uses Oppaitime metadata under the hood.
+The advanced search options are certain to change in the future.
+
+
+**Request**
+
+`ajax.php?action=browse`
+
+`&page=` — page to display (default: `1`)
+
+`&searchstr=` — string to search for
+
+`taglist`, `tags_type`, `order_by`, `order_way`, `filter_cat`, `freetorrent`, `vanityhouse`, `scene`, `haslog`, `releasetype`, `media`, `format`, `encoding`, `artistname`, `filelist`, `groupname`, `recordlabel`, `cataloguenumber`, `year`, `remastertitle`, `remasteryear`, `remasterrecordlabel`, `remastercataloguenumber` — as in advanced search
+
+
+**Response**
+
+```json
+
+```
+
+## Comments 
+
+**Request**
+
+`ajax.php?action=tcomments`
+
+`&id=` — torrent's id (required)
+
+
+**Response**
+
+```json
+
+```
+
+
+## Collage
+
+**Request**
+
+`ajax.php?action=collage`
+
+`&id=` — collage's id (required)
+
+
+**Response**
+
+```json
+
+```
+
+
+## Artist 
+
+Under construction.
+Currently not returning torrents.
+Please see the below reponse.
+
+
+**Request**
+
+`ajax.php?action=artist`
+
+`&id=` — artist's id (required)
+
+`&artistname=` — artist's name
+
+`&artistreleases=` — if set, only include groups where the artist is the main artist
+
+
+**Response**
+
+```json
+
+```
+
+
+## Top 10
+
+Fetch the Top 10 torrents, tags, or users.
+
+
+### Torrents
+
+**Request**
+
+`ajax.php?action=top10`
+
+`&limit=` — one of 10, 100, 250 (default: `10`)
+
+`&type=` — one of: torrents, tags, users (default: `torrents`)
+
+
+**Response**
+
+```json
+
+```
+
+
+### Tags
+
+```json
+
+```
+
+
+### Users
+
+```json
+
+```

docs/users.md

@@ -0,0 +1,241 @@
+# Users
+
+Endpoints related to user accounts.
+
+
+## User
+
+If you're viewing your own account, `personal->passkey` will be shown.
+
+
+**Request**
+
+`ajax.php?action=user`
+
+`&id=` — id of the user to display (required)
+
+
+**Response**
+
+```json
+
+```
+
+
+## User search 
+
+**Request**
+
+`ajax.php?action=usersearch`
+
+`&search=` — the search term (required)
+
+`&page=` — page to display (default: `1`)
+
+
+**Response**
+
+```json
+
+```
+
+
+## Community stats 
+
+**Request**
+
+`ajax.php?action=community_stats`
+
+`&userid=` — id of the user to display (required)
+
+
+**Response**
+
+```json
+
+```
+
+
+## Recents (torrents)
+
+This endpoint circumvents the "upload anonymously" feature.
+
+
+**Request**
+
+`ajax.php?action=user_recents`
+
+`&userid=` id of user (required)
+
+`&limit=` how many recent torrents to fetch
+
+
+**Response**
+
+```json
+
+```
+
+
+## History (community)
+
+**Request**
+
+`ajax.php?action=userhistory&type=posts`
+
+`&userid=` id of user (required)
+
+
+**Response**
+
+```json
+
+```
+
+
+# Your account
+
+Endpoints that only fetch info about your own account.
+
+## Inbox
+
+**Request**
+
+`ajax.php?action=inbox`
+
+`&page=` — page number to display (default: `1`)
+
+`&search=` — filter messages by search string
+
+`&searchtype=` — one of: subject, message, user
+
+`&sort=` — if set to `unread` then unread messages come first
+
+`&type=` — one of: inbox or sentbox (default: `inbox`)
+
+
+**Response**
+
+```
+
+```
+
+
+## Conversation 
+
+**Request**
+
+`ajax.php?action=inbox&type=viewconv`
+
+`&id=` — id of the message to display (required)
+
+
+**Response**
+
+```json
+
+```
+
+## Bookmarks
+
+Fetch bookmarked torrents or artists.
+
+
+### Torrents
+
+**Request**
+
+`ajax.php?action=bookmarks`
+
+`&type=` — one of torrents, artists (default: `torrents`)
+
+
+**Response**
+
+```json
+
+```
+
+### Artists
+
+```json
+
+```
+
+
+## Notifications
+
+**Request**
+
+`ajax.php?action=notifications`
+
+`&page=` — page number to display (default: `1`)
+
+
+**Response**
+
+```json
+todo
+```
+
+
+### Get user notifications
+
+**Request**
+
+`ajax.php?action=get_user_notifications`
+
+
+**Response**
+
+```json
+todo
+```
+
+
+### Clear user notification
+
+**Request**
+
+`ajax.php?action=clear_user_notification`
+
+`&type=` — one of the below NotificationsManager class constants:
+
+- Inbox
+- News
+- Blog
+- StaffPM
+- Torrents
+- Quotes
+- Subscriptions
+- Collages
+- Global
+
+
+**Response**
+
+```json
+
+```
+
+
+## Password validate
+
+Is your current password acceptable?
+
+
+**Request**
+
+`ajax.php?action=password_validate`
+
+
+**Response**
+
+```json
+{
+    "status": "success",
+    "response": {
+        "pwValidate": "true"
+    }
+}
+```

mkdocs.yml

@@ -0,0 +1 @@
+site_name: 'API ⸬ BioTorrents.de'