Max/zkldi_Tachi
1
0
Fork 0
mirror of https://github.com/zkldi/Tachi.git synced 2026-09-29 02:18:09 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
e045ed4cbfabd5c35bde2bb35780ab65400a76fa
zkldi_Tachi/old-docs/docs/api/routes/users.md
T
zk e363bd2532 docs: migrate from mkdocs to mdbook (#1558) 
* docs: migrate from mkdocs to mdbook

- Rename old mkdocs docs/ to old-docs/ for reference
- Set up new docs/ with mdbook (book.toml + src/ tree)
- Mirror full nav structure from mkdocs.yml into SUMMARY.md
- Add Justfile-docs with docs-serve, docs-build, docs-check, docs-install recipes
- Import Justfile-docs from root Justfile
- Rewrite .github/workflows/docs.yml: build step uses taiki-e/install-action
  to install mdbook, split into separate build + deploy jobs, PR builds
  run the check step too

* ci(docs): pin actions to SHAs, install mdbook via release binary

* ci(docs): install mdbook from apt instead of curling a release binary

* dev: replace mkdocs python stack with mdbook in dev image

* ci(docs): apt only works on Debian; restore release binary install for Ubuntu CI

* docs: fix duplicate file entries in SUMMARY.md

* docs: remove docs-install recipe

* docs: remove site-url from book.toml to fix asset loading

* dev: install mdbook from upstream release binary, not Debian apt

The Debian package (0.4.x+ds) strips bundled font assets, leaving the
built site without fonts/fonts.css. Use the upstream tarball (same as CI)
so the theme is complete. Handles x86_64 and aarch64.

* docs: vendor mdbook tarballs in dev/mdbook/, install from there

Dockerfile.dev uses COPY + tar to install the right arch at build time.
CI extracts the x86_64 tarball directly from the checkout.
No network access required for either — and no stripped-fonts Debian package.

* fix: unwritten
2026-05-22 20:43:07 +01:00

484 lines
9.6 KiB
Markdown
Raw Blame History

# Users
These endpoints are related to users in general.
---
## List Users
`GET /api/v1/users`
### Parameters
| Property | Type | Description |
| :-----------------: | :------: | :----------------------------------------------------------------------------------------------------: |
| `online` (Optional) | Presence | If present, this limits the returned users to those that are currently online. |
| `search` (Optional) | String | If present, this endpoint will only return users where this string is contained within their username. |
### Response
| Property | Type | Description |
| :------: | :------------------------------------------------: | :------------------------------------: |
| `<body>` | Array&lt;[UserDocument](../../schemas/user.md)&gt; | The array of up to 100 users returned. |
!!! note
Users are guaranteeably returned in order of when they were `lastSeen`.
### Example
#### Request
```
GET /api/v1/users
```
#### Response
```js
[
{
id: 1,
username: "zkldi",
// ... continued
},
];
```
---
## Retrieve user with ID
`GET /api/v1/users/:userID`
!!! note
The :userID param has some special functionality,
and any time you see it in these docs, that
functionality is supported.
You may pass the integer userID for this user - 1.
You may also pass the username - zkldihis is also case-insensitive, so you could pass zklzkldi
You may also pass the special string - `me` - which
will select whatever user you are authenticated as.
### Parameters
None.
### Response
| Property | Type | Description |
| :------: | :-----------------------------------: | :---------------------------------------: |
| `<body>` | [UserDocument](../../schemas/user.md) | The user this ID/username corresponds to. |
### Example
!!! note
`zk` is the username for the user with userID 1.
it's also the username of the person writing these
docs. Hi!
#### Request
```
GET /api/v1/users/zkldi
OR
GET /api/v1/users/1
OR
GET /api/v1/users/zkldit's case insensitive!)
OR
GET /api/v1/users/me IF authenticated as userID 1.
```
#### Response
```js
{
id: 1,
username: "zkldi
// ... so on
}
```
---
## Modify this user document.
`PATCH /api/v1/users/:userID`
### Permissions
- Self-Key level authentication as this user.
### Parameters
| Property | Type | Description |
| :----------------------------------------------------------: | :------------: | :---------------------------------------------------------------------------: |
| `about` | String | An about me. This is rendered as markdown. |
| `status` | String \| Null | The users status. If null, this will be unset. |
| `discord`, `twitter`, `github`, `steam`, `youtube`, `twitch` | String \| Null | Information about this users social media. If null, this field will be unset. |
### Response
| Property | Type | Description |
| :------: | :-----------------------------------: | :--------------------------------------------------: |
| `<body>` | [UserDocument](../../schemas/user.md) | The user document with all of those changes applied. |
### Example
#### Request
```js
{
"about": "#Hello!**I'm zkldi,
"status": "I'm cool!",
"twitter": null,
"steam": "zkldi
}
```
#### Response
```js
{
"id": 1,
"username": "zkldi
"usernameLowercase": "zkldi
"socialMedia": {
"twitter": null,
"steam": "zkldi
// this property was already here, and not modified by the request.
"discord": "chatbpd",
},
"about": "#Hello!**I'm zkldi,
"status": "I'm cool!",
// and other user props...
}
```
---
## Retrieve per-game profiles for a user.
`GET /api/v1/users/:userID/game-profiles`
### Parameters
None.
### Response
| Property | Type | Description |
| :------: | :--------------------------------------------------: | :-----------------------------------------: |
| `<body>` | Array&lt;UserGameStatsDocument & \_\_rankingData&gt; | The array of per-game profile documents (ratings and classes) this user has. |
!!! info
For UI reasons, the UserGameStatsDocuments here have an additional `__rankingData` property, which contains leaderboard ranking information for this user.
### Example
#### Request
```
GET /api/v1/users/zkldime-stats
OR
GET /api/v1/users/1/game-profiles
```
#### Response
```js
[
{
userID: 1,
game: "iidx",
playtype: "SP",
ratings: {
ktRating: 15,
},
classes: {
dan: 14,
},
__rankingData: {
ktRating: {
ranking: 15,
outOf: 74,
},
BPI: {
ranking: 12,
outOf: 74,
},
},
},
{
userID: 1,
game: "gitadora",
playtype: "Dora",
ratings: {
skill: 1404,
},
classes: {
skillColour: 1,
},
__rankingData: {
skill: {
ranking: 199,
outOf: 202,
},
},
},
];
```
!!! info
In the event a user has played no games, this will
return an empty array.
---
## Change Profile Picture
`PUT /api/v1/users/:userID/pfp`
### Permissions
- customise_profile
- Must be the owner of this profile.
### Parameters
| Property | Type | Description |
| :------: | :---------: | :-----------------------------: |
| `pfp` | JPG, or PNG | The new profile picture to set. |
!!! note
This endpoint expects multipart form data.
### Response
| Property | Type | Description |
| :------: | :----: | :--------------------------------------------------------: |
| `get` | String | This contains the URL to then GET the new profile picture. |
### Example
#### Request
```
PUT /api/v1/users/1/pfp
```
```
// this is not a real multipart request, as those things
// are huge!
pfp=<somefiledata>
```
#### Response
```json
{
"get": "/api/v1/users/1/pfp"
}
```
---
## Get a user's profile picture.
`GET /api/v1/users/:userID/pfp`
### Parameters
None.
### Response
**Not JSON**. This returns the actual JPG or PNG stored for
this user.
### Example
N/A
---
## Unset your profile picture.
`DELETE /api/v1/users/:userID/pfp`
!!! note
If you do not have a profile picture set, this will be
a 404 error.
### Permissions
- customise_profile
- Must be the owner of this profile.
### Parameters
None.
### Response
None.
### Example
Self-explanatory.
---
## Change Profile Banner
`PUT /api/v1/users/:userID/banner`
### Permissions
- customise_profile
- Must be the owner of this profile.
### Parameters
| Property | Type | Description |
| :------: | :---------: | :----------------------------: |
| `banner` | JPG, or PNG | The new profile banner to set. |
!!! note
This endpoint expects multipart form data.
### Response
| Property | Type | Description |
| :------: | :----: | :-------------------------------------------------------: |
| `get` | String | This contains the URL to then GET the new profile banner. |
### Example
#### Request
```
PUT /api/v1/users/1/banner
```
```
// this is not a real multipart request, as those things
// are huge!
banner=<somefiledata>
```
#### Response
```json
{
"get": "/api/v1/users/1/banner"
}
```
---
## Get a user's profile banner.
`GET /api/v1/users/:userID/banner`
### Parameters
None.
### Response
Not JSON. This returns the actual JPG or PNG stored for
this user.
### Example
N/A
---
---
## Unset your profile banner.
`DELETE /api/v1/users/:userID/banner`
!!! note
If you do not have a profile banner set, this is
a 404 error.
### Permissions
- customise_profile
- Must be the owner of this profile.
### Parameters
None.
## Retrieve your notifications
`GET /api/v1/users/:userID/notifications`
### Permissions
- Must be a session-request from the user who owns these notifications.
!!! note
All of the notification endpoints must be accessed by session-level authentication
from the right requesting user; viz. no api keys can access these endpoints, and
nobody can read another players notifications.
This isn't really for any security reasons, but more for privacy reasons. It feels
wrong to be able to let others read others notifications.
### Parameters
None.
### Response
| Property | Type | Description |
| :------: | :-------------------------------: | :----------------------------------------------------------------------------------: |
| `<body>` | Array&lt;NotificationDocument&gt; | An array of all of this users notifications, sorted by most recently recieved first. |
---
## Mark all of your notifications as read.
`POST /api/v1/users/:userID/notifications/mark-all-read`
!!! info
This endpoints marks all of a users notifications as read, and is intended for a UI
to invoke this request when they open their inbox.
### Permissions
- Must be a session-level request from the user who owns these notifications.
### Parameters
None.
### Response
None. (Empty Object)
---
## Clear all notifications from your inbox.
`POST /api/v1/users/:userID/notifications/delete-all`
### Permissions
- Must be a session-level request from the user who owns these notifications.
### Parameters
None.
### Response
None. (Empty Object)
Reference in New Issue View Git Blame Copy Permalink