versia-pub/server
2
0
Fork 0
mirror of https://github.com/versia-pub/server.git synced 2025-12-06 00:18:19 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: 📝 Update docs to reflect latest changes

Browse source
This commit is contained in:
Jesse Wierzbinski 2025-05-19 15:05:22 +02:00
parent d12bbb2a1b
commit e50c8b6a5b
No known key found for this signature in database
8 changed files with 9 additions and 1037 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
docs/.vitepress/config.ts
View file

@ -54,26 +54,14 @@ export default defineConfig({
{
text: "API",
items: [
{
text: "Emojis",
link: "/api/emojis",
},
{
text: "Reactions",
link: "/api/reactions",
},
{
text: "Roles",
link: "/api/roles",
},
{
text: "Challenges",
link: "/api/challenges",
},
{
text: "SSO",
link: "/api/sso",
},
{
text: "Mastodon Extensions",
link: "/api/mastodon",

50
docs/api/challenges.md
View file

@ -8,57 +8,9 @@ This is a form of proof of work CAPTCHA, and should be mostly invisible to users
Challenges are powered by the [Altcha](https://altcha.org/) library. You may either reimplement their solution code (which is very simple), or use [`altcha-lib`](https://github.com/altcha-org/altcha-lib) to solve the challenges.
## Challenge
```typescript
type UUID = string;
interface Challenge {
id: UUID;
algorithm: "SHA-256" | "SHA-384" | "SHA-512";
challenge: string;
maxnumber?: number;
salt: string;
signature: string;
}
```
## Request Challenge
```http
POST /api/v1/challenges
```
Generates a new challenge for the client to solve.
- **Returns:**: [`Challenge`](#challenge)
- **Authentication:**: Not required
- **Permissions:**: None
- **Version History**:
- `0.7.0`: Added.
### Example
```http
POST /api/v1/challenges
```
### Response
#### `200 OK`
Challenge data.
```json
{
"id":"01931621-1456-7b5b-be65-c044e6b47cbb",
"salt":"d15e43fa3709d85ce3c74644?challenge_id=01931621-1456-7b5b-be65-c044e6b47cbb&expires=1731243386",
"algorithm":"SHA-256",
"challenge":"5dc6b352632912664583940e14b9dfbdf447459d4517708ce8766a39ac040eb5",
"maxnumber":50000,
"signature":"22c3a687dc2500cbffcb022ae8474360d5c2f63a50ba376325c211bb2ca06b7f"
}
```
To request a challenge, you may use the [`POST /api/v1/challenges`](https://vs.cpluspatch.com/docs#tag/challenges/POST/api/v1/challenges) endpoint.
## Sending a Solution

204
docs/api/emojis.md
View file

@ -1,204 +0,0 @@
# Emoji API
This API allows users to create, read, update, and delete instance custom emojis.
The **Versia Server CLI** can also be used to manage custom emojis.
## Emoji
```typescript
type UUID = string;
type URL = string;
interface Emoji {
id: UUID;
shortcode: string;
url: URL;
static_url?: URL;
visible_in_picker: boolean;
category?: string;
}
```
## Create Emoji
```http
POST /api/v1/emojis
```
Upload a new custom emoji.
- **Returns:** [`Emoji`](#emoji)
- **Authentication:** Required
- **Permissions:** `owner:emoji`, or `emoji` if uploading a global emoji.
- **Version History**:
- `0.7.0`: Added.
### Request
- `shortcode` (string, required): The shortcode for the emoji.
- 1-64 characters long, alphanumeric, and may contain dashes or underscores.
- `element` (file/string, required): The image file to upload.
- Can be a URL, or a file upload (`multipart/form-data`).
- `alt` (string): Emoji alt text.
- `category` (string): Emoji category. Can be any string up to 64 characters long.
- `global` (boolean): If set to `true`, the emoji will be visible to all users, not just the uploader.
- Requires `emoji` permission.
#### Example
```http
POST /api/v1/emojis
Content-Type: application/json
Authorization: Bearer ...
{
"shortcode": "blobfox-coffee",
"element": "https://example.com/blobfox-coffee.png",
"alt": "My emoji",
"category": "Blobmojis"
}
```
### Response
#### `201 Created`
Emoji successfully uploaded.
```json
{
"id": "f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b",
"shortcode": "blobfox-coffee",
"url": "https://cdn.yourinstance.com/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b.png",
"static_url": "https://cdn.yourinstance.com/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b.png",
"visible_in_picker": true,
"category": "Blobmojis"
}
```
## Get Emoji
```http
GET /api/v1/emojis/:id
```
Get a specific custom emoji.
- **Returns:** [`Emoji`](#emoji)
- **Authentication:** Required
- **Permissions:** `owner:emoji`, or `emoji` if viewing a global emoji.
- **Version History**:
- `0.7.0`: Added.
### Request
#### Example
```http
GET /api/v1/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b
Authorization: Bearer ...
```
### Response
#### `200 OK`
Custom emoji data.
```json
{
"id": "f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b",
"shortcode": "blobfox-coffee",
"url": "https://cdn.yourinstance.com/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b.png",
"static_url": "https://cdn.yourinstance.com/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b.png",
"visible_in_picker": true,
"category": "Blobmojis"
}
```
## Edit Emoji
```http
PATCH /api/v1/emojis/:id
```
Edit an existing custom emoji.
- **Returns:** [`Emoji`](#emoji)
- **Authentication:** Required
- **Permissions:** `owner:emoji`, or `emoji` if editing a global emoji.
- **Version History**:
- `0.7.0`: Added.
### Request
> [!NOTE]
> All fields are optional.
- `shortcode` (string): The shortcode for the emoji.
- 1-64 characters long, alphanumeric, and may contain dashes or underscores.
- `element` (file/string): The image file to upload.
- Can be a URL, or a file upload (`multipart/form-data`).
- `alt` (string): Emoji alt text.
- `category` (string): Emoji category. Can be any string up to 64 characters long.
- `global` (boolean): If set to `true`, the emoji will be visible to all users, not just the uploader.
- Requires `emoji` permission.
#### Example
```http
PATCH /api/v1/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b
Content-Type: application/json
Authorization: Bearer ...
{
"category": "Blobfoxes"
}
```
### Response
#### `200 OK`
Emoji successfully edited.
```json
{
"id": "f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b",
"shortcode": "blobfox-coffee",
"url": "https://cdn.yourinstance.com/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b.png",
"static_url": "https://cdn.yourinstance.com/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1b1b.png",
"visible_in_picker": true,
"category": "Blobfoxes"
}
```
## Delete Emoji
```http
DELETE /api/v1/emojis/:id
```
Delete an existing custom emoji.
- **Returns:** `204 No Content`
- **Authentication:** Required
- **Permissions:** `owner:emoji`, or `emoji` if deleting a global emoji.
- **Version History**:
- `0.7.0`: Added.
### Request
#### Example
```http
DELETE /api/v1/emojis/f7b1c1b0-0b1b-4b1b-8b1b-0b1b1b1b1
Authorization: Bearer ...
```
### Response
#### `204 No Content`
Emoji successfully deleted.

2
docs/api/mastodon.md
View file

@ -363,7 +363,7 @@ type ExtendedAccount = Account & {
### `roles`
An array of [`Roles`](./roles.md#role) that the user has.
An array of `Roles` that the user has.
### `uri`

601
docs/api/roles.md
View file

@ -1,601 +0,0 @@
# Roles API
This API allows users to create, read, update, delete and assign instance custom roles. Custom roles can be used to grant users specific permissions, such as managing the instance, uploading custom emojis, or moderating content.
## Priorities
Every role has a "priority" value, which determines the order in which roles are applied. Roles with higher priorities take precedence over roles with lower priorities. The default priority is `0`.
Additionally, users cannot edit roles with a higher priority than their highest priority role.
## Visibility
Roles can be visible or invisible. Invisible roles are not shown to users in the UI, but they can still be managed via the API. This is useful for cosmetic roles that do not grant any permissions, e.g. `#1 Most Prominent Glizzy Eater`.
## Permissions
Default permissions for anonymous users, logged-in users, and administrators can be set in the configuration. These permissions are always applied in addition to the permissions granted by roles. You may set them to empty arrays to exclusively use roles for permissions (make sure your roles are set up correctly).
### List of Permissions
- `Manage` permissions grant the ability to create, read, update, and delete resources.
- `View` permissions grant the ability to read resources.
- `Owner` permissions grant the ability to manage resources that the user owns.
```ts
ManageNotes: "notes",
ManageOwnNotes: "owner:note",
ViewNotes: "read:note",
ViewNoteLikes: "read:note_likes",
ViewNoteBoosts: "read:note_boosts",
ManageAccounts: "accounts",
ManageOwnAccount: "owner:account",
ViewAccountFollows: "read:account_follows",
ManageLikes: "likes",
ManageOwnLikes: "owner:like",
ManageBoosts: "boosts",
ManageOwnBoosts: "owner:boost",
ViewAccounts: "read:account",
ManageEmojis: "emojis",
ViewEmojis: "read:emoji",
ManageOwnEmojis: "owner:emoji",
ViewReactions: "read:reaction",
ManageReactions: "reactions",
ManageOwnReactions: "owner:reaction",
ManageMedia: "media",
ManageOwnMedia: "owner:media",
ManageBlocks: "blocks",
ManageOwnBlocks: "owner:block",
ManageFilters: "filters",
ManageOwnFilters: "owner:filter",
ManageMutes: "mutes",
ManageOwnMutes: "owner:mute",
ManageReports: "reports",
ManageOwnReports: "owner:report",
ManageSettings: "settings",
ManageOwnSettings: "owner:settings",
ManageRoles: "roles",
ManageNotifications: "notifications",
ManageOwnNotifications: "owner:notification",
ManageFollows: "follows",
ManageOwnFollows: "owner:follow",
ManageOwnApps: "owner:app",
Search: "search",
UsePushNotifications: "push_notifications",
ViewPublicTimelines: "public_timelines",
ViewPrimateTimelines: "private_timelines",
IgnoreRateLimits: "ignore_rate_limits",
Impersonate: "impersonate",
ManageInstance: "instance",
ManageInstanceFederation: "instance:federation",
ManageInstanceSettings: "instance:settings",
/** Users who do not have this permission will not be able to login! */
OAuth: "oauth",
```
An example usage of these permissions would be to not give the `ViewPublicTimelines` permission to anonymous users, but give it to logged-in users, in order to restrict access to public timelines.
### Manage Roles
The `roles` permission allows the user to manage roles, including adding and removing roles from themselves. This permission is required to use the Roles API.
### Impersonate
The `impersonate` permission allows the user to impersonate other users (logging in with their credentials). This is a dangerous permission and should be used with caution.
Useful for administrators who need to troubleshoot user issues.
### OAuth
The `oauth` permission is required for users to log in via OAuth. Users who do not have this permission will not be able to log in via OAuth.
## Role
```ts
type UUID = string;
type URL = string;
type Permission = string;
interface Role {
id: UUID;
name: string;
permissions: Permission[];
priority: number;
description?: string | null;
visible: boolean;
icon?: URL | null;
}
```
## Get All Roles
```http
GET /api/v1/roles
```
Get a list of all roles on the instance.
- **Returns**: Array of [`Role`](#role)
- **Authentication**: Not required
- **Permissions**: None
- **Version History**:
- `0.7.0`: Added.
- `0.8.0`: Now returns all instance roles.
### Request
#### Example
```http
GET /api/v1/roles
Authorization: Bearer ...
```
### Response
#### `200 OK`
All roles on the instance.
```json
[
{
"id": "default",
"name": "Default",
"permissions": [
"owner:note",
"read:note",
"read:note_likes",
"read:note_boosts",
"owner:account",
"read:account_follows",
"owner:like",
"owner:boost",
"read:account",
"owner:emoji",
"read:emoji",
"owner:media",
"owner:block",
"owner:filter",
"owner:mute",
"owner:report",
"owner:settings",
"owner:notification",
"owner:follow",
"owner:app",
"search",
"public_timelines",
"private_timelines",
"oauth"
],
"priority": 0,
"description": "Default role for all users",
"visible": false,
"icon": null
},
{
"id": "admin",
"name": "Admin",
"permissions": [
"owner:note",
"read:note",
"read:note_likes",
"read:note_boosts",
"owner:account",
"read:account_follows",
"owner:like",
"owner:boost",
"read:account",
"owner:emoji",
"read:emoji",
"owner:media",
"owner:block",
"owner:filter",
"owner:mute",
"owner:report",
"owner:settings",
"owner:notification",
"owner:follow",
"owner:app",
"search",
"public_timelines",
"private_timelines",
"oauth",
"notes",
"accounts",
"likes",
"boosts",
"emojis",
"media",
"blocks",
"filters",
"mutes",
"reports",
"settings",
"roles",
"notifications",
"follows",
"impersonate",
"ignore_rate_limits",
"instance",
"instance:federation",
"instance:settings"
],
"priority": 2147483647,
"description": "Default role for all administrators",
"visible": false,
"icon": null
}
]
```
## Get Role
```http
GET /api/v1/roles/:id
```
Get a specific role's data.
- **Returns**: [`Role`](#role)
- **Authentication**: Required
- **Permissions**: None
- **Version History**:
- `0.7.0`: Added.
### Request
#### Example
```http
GET /api/v1/roles/default
Authorization: Bearer ...
```
### Response
#### `200 OK`
Role data.
```json
{
"id": "default",
"name": "Default",
"permissions": [
"owner:note",
"read:note",
"read:note_likes",
"read:note_boosts",
"owner:account",
"read:account_follows",
"owner:like",
"owner:boost",
"read:account",
"owner:emoji",
"read:emoji",
"owner:media",
"owner:block",
"owner:filter",
"owner:mute",
"owner:report",
"owner:settings",
"owner:notification",
"owner:follow",
"owner:app",
"search",
"public_timelines",
"private_timelines",
"oauth"
],
"priority": 0,
"description": "Default role for all users",
"visible": false,
"icon": null
}
```
## Create Role
```http
POST /api/v1/roles
```
Create a new role.
- **Returns**: [`Role`](#role)
- **Authentication**: Required
- **Permissions**: `roles`
- **Version History**:
- `0.8.0`: Added.
### Request
- `name` (string, required): The name of the role.
- 1-128 characters.
- `permissions` (array of strings, optional): The permissions granted by the role. Defaults to an empty array.
- `priority` (number, optional): The priority of the role. Defaults to `0`.
- `description` (string, optional): A description of the role.
- `visible` (boolean, optional): Whether the role is visible in the UI. Defaults to `false`.
- `icon` (string, optional): An icon URL for the role.
#### Example
```http
POST /api/v1/roles
Authorization: Bearer ...
Content-Type: application/json
{
"name": "Moderator",
"permissions": [
"notes",
"accounts",
"likes",
"boosts",
"emojis",
"media",
"blocks",
"filters",
"mutes",
"reports",
"settings",
"roles",
"notifications",
"follows",
"impersonate",
"ignore_rate_limits",
"instance",
"instance:federation",
"instance:settings"
],
"priority": 100,
"description": "Moderator role for managing content",
"visible": true,
"icon": "https://example.com/moderator.png"
}
```
### Response
#### `201 Created`
Role successfully created.
```json
{
"id": "364fd13f-28b5-4e88-badd-ce3e533f0d02",
"name": "Moderator",
"permissions": [
"notes",
"accounts",
"likes",
"boosts",
"emojis",
"media",
"blocks",
"filters",
"mutes",
"reports",
"settings",
"roles",
"notifications",
"follows",
"impersonate",
"ignore_rate_limits",
"instance",
"instance:federation",
"instance:settings"
],
"priority": 100,
"description": "Moderator role for managing content",
"visible": true,
"icon": "https://example.com/moderator.png"
}
```
## Update Role
```http
PATCH /api/v1/roles/:id
```
Update a role's data.
- **Returns**: `204 No Content`
- **Authentication**: Required
- **Permissions**: `roles`
- **Version History**:
- `0.8.0`: Added.
### Request
- `name` (string, optional): The name of the role.
- 1-128 characters.
- `permissions` (array of strings, optional): The permissions granted by the role. Defaults to an empty array.
- `priority` (number, optional): The priority of the role. Defaults to `0`.
- `description` (string, optional): A description of the role.
- `visible` (boolean, optional): Whether the role is visible in the UI. Defaults to `false`.
- `icon` (string, optional): An icon URL for the role.
#### Example
```http
PATCH /api/v1/roles/364fd13f-28b5-4e88-badd-ce3e533f0d02
Authorization: Bearer ...
Content-Type: application/json
{
"name": "Moderator",
"permissions": [
"notes",
"accounts",
"likes",
"boosts",
"emojis",
"media",
"blocks",
"filters",
"mutes",
],
"priority": 10,
"description": "Moderator role for managing content",
"visible": true,
"icon": "https://example.com/moderator.png"
}
```
### Response
#### `204 No Content`
Role successfully updated.
## Delete Role
```http
DELETE /api/v1/roles/:id
```
Delete a role.
- **Returns**: `204 No Content`
- **Authentication**: Required
- **Permissions**: `roles`
- **Version History**:
- `0.8.0`: Added.
### Request
#### Example
```http
DELETE /api/v1/roles/364fd13f-28b5-4e88-badd-ce3e533f0d
Authorization: Bearer ...
```
### Response
#### `204 No Content`
Role successfully deleted.
## Assign Role
```http
POST /api/v1/accounts/:id/roles/:role_id
```
Assign a role to an account.
- **Returns**: `204 No Content`
- **Authentication**: Required
- **Permissions**: `roles`
- **Version History**:
- `0.8.0`: Added.
### Request
#### Example
```http
POST /api/v1/accounts/04608f74-6263-4a9a-bd7a-e778d4ac2ce4/roles/364fd13f-28b5-4e88-badd-ce3e533
Authorization: Bearer ...
```
### Response
#### `204 No Content`
Role successfully assigned.
## Unassign Role
```http
DELETE /api/v1/accounts/:id/roles/:role_id
```
Unassign a role from an account.
- **Returns**: `204 No Content`
- **Authentication**: Required
- **Permissions**: `roles`
- **Version History**:
- `0.8.0`: Added.
### Request
#### Example
```http
DELETE /api/v1/accounts/04608f74-6263-4a9a-bd7a-e778d4ac2ce4/roles/364fd13f-28b5-4e88-badd-ce3e533
Authorization: Bearer ...
```
### Response
#### `204 No Content`
Role successfully unassigned.
## Get Account Roles
```http
GET /api/v1/accounts/:id/roles
```
Get a list of roles assigned to an account.
- **Returns**: Array of [`Role`](#role)
- **Authentication**: Not required
- **Permissions**: None
- **Version History**:
- `0.8.0`: Added.
### Request
#### Example
```http
GET /api/v1/accounts/04608f74-6263-4a9a-bd7a-e778d4ac2ce4/roles
```
### Response
#### `200 OK`
Roles assigned to the account.
```json
[
{
"id": "364fd13f-28b5-4e88-badd-ce3e533f0d02",
"name": "Moderator",
"permissions": [
"notes",
"accounts",
"likes",
"boosts",
"emojis",
"media",
"blocks",
"filters",
"mutes",
"reports",
"settings",
"roles",
"notifications",
"follows",
"impersonate",
"ignore_rate_limits",
"instance",
"instance:federation",
"instance:settings"
],
"priority": 100,
"description": "Moderator role for managing content",
"visible": true,
"icon": "https://example.com/moderator.png"
}
]
```

164
docs/api/sso.md
View file

@ -1,164 +0,0 @@
# SSO API
The SSO API is used to link, unlink, and list external OpenID Connect providers that the user has linked their account to.
## SSO Provider
```ts
interface SSOProvider {
id: string;
name: string;
icon: string;
}
```
## SSO Link
```http
POST /api/v1/sso
```
Allows users to link their account to an external OpenID Connect provider.
- **Returns**: Link to redirect the user to the external provider.
- **Authentication**: Required
- **Permissions**: `oauth`
- **Version History**:
- `0.6.0`: Added.
- `0.7.0`: Permissions added.
### Request
- `issuer` (string, required): The issuer ID of the OpenID Connect provider as set in config.
#### Example
```http
POST /api/v1/sso
Authorization: Bearer ...
Content-Type: application/json
{
"issuer": "google"
}
```
### Response
#### `200 OK`
Link to redirect the user to the external provider's page.
```json
{
"link": "https://accounts.google.com/o/oauth2/auth?client_id=..."
}
```
## SSO Unlink
```http
DELETE /api/v1/sso/:issuer
```
Allows users to unlink their account from an external OpenID Connect provider.
- **Returns**: `204 No Content`
- **Authentication**: Required
- **Permissions**: `oauth`
- **Version History**:
- `0.6.0`: Added.
- `0.7.0`: Permissions added.
### Request
#### Example
```http
DELETE /api/v1/sso/google
Authorization: Bearer ...
```
### Response
#### `204 No Content`
Account successfully unlinked.
## List Connected Providers
```http
GET /api/v1/sso
```
Lists all external OpenID Connect providers that the user has linked their account to.
- **Returns**: Array of [`SSOProvider`](#ssoprovider) objects.
- **Authentication**: Required
- **Permissions**: `oauth`
- **Version History**:
- `0.6.0`: Added.
- `0.7.0`: Permissions added.
### Request
#### Example
```http
GET /api/v1/sso
Authorization: Bearer ...
```
### Response
#### `200 OK`
Array of [`SSOProvider`](#ssoprovider) objects.
```json
[
{
"id": "google",
"name": "Google",
"icon": "https://cdn.example.com/google.png"
}
]
```
## Get Linked Provider Data
```http
GET /api/v1/sso/:issuer
```
Gets the data of an external OpenID Connect provider that the user has linked their account to.
- **Returns**: [`SSOProvider`](#ssoprovider) object.
- **Authentication**: Required
- **Permissions**: `oauth`
- **Version History**:
- `0.6.0`: Added.
- `0.7.0`: Permissions added.
### Request
#### Example
```http
GET /api/v1/sso/google
Authorization: Bearer ...
```
### Response
#### `200 OK`
[`SSOProvider`](#ssoprovider) object.
```json
{
"id": "google",
"name": "Google",
"icon": "https://cdn.example.com/google.png"
}
```

2
docs/index.md
View file

@ -10,7 +10,7 @@ features:
- icon: 🖥
title: API Reference
details: Writing your own client? Check out the API reference
link: ./api/emojis
link: ./api/challenges
- icon: 📚
title: Frontend Building
details: Information on developing your own frontend

7
docs/setup/nix.md
View file

@ -27,7 +27,10 @@ nixosConfigurations = {
system = "x86_64-linux"; # arm64-linux is also supported
modules = [
# ...
versia-server.nixosModules.default
{
nixpkgs.overlays = [versia-server.overlays.default];
}
versia-server.nixosModules.versia-server
];
};
};
@ -42,7 +45,6 @@ This module exposes the following configuration option:
```nix
services.versia-server = {
enable = true;
dataDir = "/var/lib/versia-server";
user = "versia-server";
group = "versia-server";
@ -79,7 +81,6 @@ services.versia-server = {
### Configuration Options
- `enable`: Whether to enable the service. Default: `true`.
- `dataDir`: The directory where the data will be stored. Default: `/var/lib/versia-server`.
- `user`: The user under which the service will run. Default: `versia-server`.
- `group`: The group under which the service will run. Default: `versia-server`.
- `nodes`: A set of nodes to run. Each node can have its own configuration overrides, which will be merged with the default configuration. You must have at least one of each type (`api` and `worker`).