mirror of https://github.com/zkldi/Tachi.git synced 2026-09-27 09:28:12 +03:00

Files

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

9.6 KiB

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<UserDocument>	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

[
	{
		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	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

{
	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	The user document with all of those changes applied.

Example

Request

{
	"about": "#Hello!**I'm zkldi,
	"status": "I'm cool!",
	"twitter": null,
	"steam": "zkldi
}

Response

{
	"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<UserGameStatsDocument & __rankingData>	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

[
	{
		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

{
	"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

{
	"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<NotificationDocument>	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)

9.6 KiB Raw Blame History

Users

List Users

Parameters

Response

Example

Request

Response

Retrieve user with ID

Parameters

Response

Example

Request

Response

Modify this user document.

Permissions

Parameters

Response

Example

Request

Response

Retrieve per-game profiles for a user.

Parameters

Response

Example

Request

Response

Change Profile Picture

Permissions

Parameters

Response

Example

Request

Response

Get a user's profile picture.

Parameters

Response

Example

Unset your profile picture.

Permissions

Parameters

Response

Example

Change Profile Banner

Permissions

Parameters

Response

Example

Request

Response

Get a user's profile banner.

Parameters

Response

Example

Unset your profile banner.

Permissions

Parameters

Retrieve your notifications

Permissions

Parameters

Response

Mark all of your notifications as read.

Permissions

Parameters

Response

Clear all notifications from your inbox.

Permissions

Parameters

Response

9.6 KiB

Raw Blame History