2024-05-17 03:50:13 +02:00
# Mastodon API Extensions
2024-11-10 15:24:34 +01:00
Versia Server extends several Mastodon API endpoints to provide additional functionality. These endpoints are not part of the official Mastodon API, but are provided by Versia Server to enhance the user experience.
## Refetch User
```http
POST /api/v1/accounts/:id/refetch
```
Refetches the user's profile information from remote servers. Does not work for local users.
- **Returns**: [`Account` ](https://docs.joinmastodon.org/entities/Account/ )
- **Authentication**: Required
- **Permissions**: `read:account`
- **Version History**:
- `0.7.0` : Added.
### Request
#### Example
```http
POST /api/v1/accounts/364fd13f-28b5-4e88-badd-ce3e533f0d02/refetch
Authorization: Bearer ...
```
### Response
#### `400 Bad Request`
The user is a local user and cannot be refetched.
#### `200 OK`
New user data.
Example from the [Mastodon API documentation ](https://docs.joinmastodon.org/entities/Account/ ):
```json
{
"id": "23634",
"username": "noiob",
"acct": "noiob@awoo.space",
"display_name": "ikea shark fan account",
"locked": false,
"bot": false,
"created_at": "2017-02-08T02:00:53.274Z",
"note": "< p > :ms_rainbow_flag: < a href = \"https://awoo.space/tags/awoo \" class = \"mention hashtag \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> #< span > awoo< /span}.space < a href = \"https://awoo.space/tags/admin \" class = \"mention hashtag \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> #< span > admin< /span} ~ < a href = \"https://awoo.space/tags/bi \" class = \"mention hashtag \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> #< span > bi< /span} ~ < a href = \"https://awoo.space/tags/nonbinary \" class = \"mention hashtag \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> #< span > nonbinary< /span} ~ compsci student ~ likes video < a href = \"https://awoo.space/tags/games \" class = \"mention hashtag \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> #< span > games< /span} and weird/ old electronics and will post obsessively about both ~ avatar by < span class = \"h-card \">< a href = \"https://weirder.earth/@dzuk \" class = \"u-url mention \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> @< span > dzuk< /span}</ span ></ p > ",
"url": "https://awoo.space/@noiob",
"avatar": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
"avatar_static": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
"header": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
"header_static": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
"followers_count": 547,
"following_count": 404,
"statuses_count": 28468,
"last_status_at": "2019-11-17",
"emojis": [
{
"shortcode": "ms_rainbow_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/028/691/original/6de008d6281f4f59.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/028/691/static/6de008d6281f4f59.png",
"visible_in_picker": true
},
{
"shortcode": "ms_bisexual_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/050/744/original/02f94a5fca7eaf78.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/050/744/static/02f94a5fca7eaf78.png",
"visible_in_picker": true
},
{
"shortcode": "ms_nonbinary_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/105/099/original/8106088bd4782072.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/105/099/static/8106088bd4782072.png",
"visible_in_picker": true
}
],
"fields": [
{
"name": "Pronouns",
"value": "they/them",
"verified_at": null
},
{
"name": "Alt",
"value": "< span class = \"h-card \">< a href = \"https://cybre.space/@noiob \" class = \"u-url mention \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> @< span > noiob< /span}</ span > ",
"verified_at": null
},
{
"name": "Bots",
"value": "< span class = \"h-card \">< a href = \"https://botsin.space/@darksouls \" class = \"u-url mention \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> @< span > darksouls< /span}</ span > , < span class = \"h-card \">< a href = \"https://botsin.space/@nierautomata \" class = \"u-url mention \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> @< span > nierautomata< /span}</ span > , < span class = \"h-card \">< a href = \"https://mastodon.social/@fedi \" class = \"u-url mention \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> @< span > fedi< /span}</ span > , code for < span class = \"h-card \">< a href = \"https://botsin.space/@awoobot \" class = \"u-url mention \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> @< span > awoobot< /span}</ span > ",
"verified_at": null
},
{
"name": "Website",
"value": "< a href = \"http://shork.xyz \" rel = \"nofollow noopener noreferrer \" target = \"_blank \">< span class = \"invisible \"> http://</ span >< span class = \"\"> shork.xyz</span >< span class = \"invisible \"> < /span}",
"verified_at": "2019-11-10T10:31:10.744+00:00"
}
]
}
```
## Get User By Username
```http
GET /api/v1/accounts/id?username=:username
```
Retrieves a user by their username.
- **Returns**: [`Account` ](https://docs.joinmastodon.org/entities/Account/ )
- **Authentication**: Not required
- **Permissions**: `read:account`
- **Version History**:
- `0.7.0` : Added.
### Request
#### Example
```http
GET /api/v1/accounts/id?username=bobleponge
```
### Response
#### `404 Not Found`
No user with that username was found.
#### `200 OK`
User data.
Example from the [Mastodon API documentation ](https://docs.joinmastodon.org/entities/Account/ ):
```json
{
"id": "23634",
"username": "noiob",
"acct": "noiob@awoo.space",
"display_name": "ikea shark fan account",
"locked": false,
"bot": false,
"created_at": "2017-02-08T02:00:53.274Z",
"note": "< p > :ms_rainbow_flag: < a href = \"https://awoo.space/tags/awoo \" class = \"mention hashtag \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> #< span > awoo< /span}.space < a href = \"https://awoo.space/tags/admin \" class = \"mention hashtag \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> #< span > admin< /span} ~ < a href = \"https://awoo.space/tags/bi \" class = \"mention hashtag \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> #< span > bi< /span} ~ < a href = \"https://awoo.space/tags/nonbinary \" class = \"mention hashtag \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> #< span > nonbinary< /span} ~ compsci student ~ likes video < a href = \"https://awoo.space/tags/games \" class = \"mention hashtag \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> #< span > games< /span} and weird/ old electronics and will post obsessively about both ~ avatar by < span class = \"h-card \">< a href = \"https://weirder.earth/@dzuk \" class = \"u-url mention \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> @< span > dzuk< /span}</ span ></ p > ",
"url": "https://awoo.space/@noiob",
"avatar": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
"avatar_static": "https://files.mastodon.social/accounts/avatars/000/023/634/original/6ca8804dc46800ad.png",
"header": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
"header_static": "https://files.mastodon.social/accounts/headers/000/023/634/original/256eb8d7ac40f49a.png",
"followers_count": 547,
"following_count": 404,
"statuses_count": 28468,
"last_status_at": "2019-11-17",
"emojis": [
{
"shortcode": "ms_rainbow_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/028/691/original/6de008d6281f4f59.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/028/691/static/6de008d6281f4f59.png",
"visible_in_picker": true
},
{
"shortcode": "ms_bisexual_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/050/744/original/02f94a5fca7eaf78.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/050/744/static/02f94a5fca7eaf78.png",
"visible_in_picker": true
},
{
"shortcode": "ms_nonbinary_flag",
"url": "https://files.mastodon.social/custom_emojis/images/000/105/099/original/8106088bd4782072.png",
"static_url": "https://files.mastodon.social/custom_emojis/images/000/105/099/static/8106088bd4782072.png",
"visible_in_picker": true
}
],
"fields": [
{
"name": "Pronouns",
"value": "they/them",
"verified_at": null
},
{
"name": "Alt",
"value": "< span class = \"h-card \">< a href = \"https://cybre.space/@noiob \" class = \"u-url mention \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> @< span > noiob< /span}</ span > ",
"verified_at": null
},
{
"name": "Bots",
"value": "< span class = \"h-card \">< a href = \"https://botsin.space/@darksouls \" class = \"u-url mention \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> @< span > darksouls< /span}</ span > , < span class = \"h-card \">< a href = \"https://botsin.space/@nierautomata \" class = \"u-url mention \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> @< span > nierautomata< /span}</ span > , < span class = \"h-card \">< a href = \"https://mastodon.social/@fedi \" class = \"u-url mention \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> @< span > fedi< /span}</ span > , code for < span class = \"h-card \">< a href = \"https://botsin.space/@awoobot \" class = \"u-url mention \" rel = \"nofollow noopener noreferrer \" target = \"_blank \"> @< span > awoobot< /span}</ span > ",
"verified_at": null
},
{
"name": "Website",
"value": "< a href = \"http://shork.xyz \" rel = \"nofollow noopener noreferrer \" target = \"_blank \">< span class = \"invisible \"> http://</ span >< span class = \"\"> shork.xyz</span >< span class = \"invisible \"> < /span}",
"verified_at": "2019-11-10T10:31:10.744+00:00"
}
]
}
```
## Get Instance TOS
```http
GET /api/v1/instance/tos
```
Returns the instance's Terms of Service, as configured in the instance settings.
- **Returns**: [`ExtendedDescription` ](https://docs.joinmastodon.org/entities/ExtendedDescription/ )
- **Authentication**: Not required
- **Permissions**: None
- **Version History**:
- `0.7.0` : Added.
### Request
#### Example
```http
GET /api/v1/instance/tos
```
### Response
#### `200 OK`
Instance's Terms of Service.
```json
{
"updated_at": "2019-11-17T00:00:00.000Z",
"content": "< h1 > TOS</ h1 > \n< p > These are the terms of service for this instance.</ p > ",
}
```
## Get Instance Privacy Policy
```http
GET /api/v1/instance/privacy_policy
```
Returns the instance's Privacy Policy, as configured in the instance settings.
- **Returns**: [`ExtendedDescription` ](https://docs.joinmastodon.org/entities/ExtendedDescription/ )
- **Authentication**: Not required
- **Permissions**: None
- **Version History**:
- `0.7.0` : Added.
### Request
#### Example
```http
GET /api/v1/instance/privacy_policy
```
### Response
#### `200 OK`
Instance's Privacy Policy.
```json
{
"updated_at": "2019-11-17T00:00:00.000Z",
"content": "< h1 > Privacy Policy</ h1 > \n< p > This is the privacy policy for this instance.</ p > ",
}
```
2024-05-17 03:50:13 +02:00
## `/api/v1/instance`
2024-11-10 15:24:34 +01:00
Extra attributes have been added to the `/api/v1/instance` endpoint.
2024-05-17 03:50:13 +02:00
```ts
2024-11-10 15:24:34 +01:00
interface SSOProvider {
id: string;
name: string;
icon?: string;
}
type ExtendedInstance = Instance & {
2024-05-17 03:50:13 +02:00
banner: string | null;
2024-08-19 15:16:01 +02:00
versia_version: string;
2024-05-17 03:50:13 +02:00
sso: {
forced: boolean;
2024-11-10 15:24:34 +01:00
providers: SSOProvider[];
};
2024-05-17 03:50:13 +02:00
}
```
### `banner`
2024-11-10 15:24:34 +01:00
The URL of the instance's banner image.
2024-05-17 03:50:13 +02:00
2024-08-19 15:16:01 +02:00
### `versia_version`
2024-05-17 03:50:13 +02:00
2024-11-10 15:24:34 +01:00
The version of Versia Server running on the instance.
2024-05-17 03:50:13 +02:00
2024-06-11 21:55:40 +02:00
The normal `version` field is always set to `"4.3.0+glitch"` or similar, to not confuse clients that expect a Mastodon instance.
2024-05-17 03:50:13 +02:00
### `sso`
Single Sign-On (SSO) settings for the instance. This object contains two fields:
- `forced` : If this is enabled, normal identifier/password login is disabled and login must be done through SSO.
- `providers` : An array of external OpenID Connect providers that users can link their accounts to. Each provider object contains the following fields:
- `id` : The issuer ID of the OpenID Connect provider.
- `name` : The name of the provider.
- `icon` : The URL of the provider's icon. Optional.
## `/api/v2/instance`
2024-11-10 15:24:34 +01:00
Extra attributes have been added to the `/api/v2/instance` endpoint. These are identical to the `/api/v1/instance` endpoint, except that the `banner` attribute uses the normal Mastodon API attribute.
```ts
type ExtendedInstanceV2 = Instance & {
versia_version: string;
sso: {
forced: boolean;
providers: SSOProvider[];
};
}
```
### `versia_version`
The version of Versia Server running on the instance.
The normal `version` field is always set to `"4.3.0+glitch"` or similar, to not confuse clients that expect a Mastodon instance.
### `sso`
Single Sign-On (SSO) settings for the instance. This object contains two fields:
- `forced` : If this is enabled, normal identifier/password login is disabled and login must be done through SSO.
- `providers` : An array of external OpenID Connect providers that users can link their accounts to. Each provider object contains the following fields:
- `id` : The issuer ID of the OpenID Connect provider.
- `name` : The name of the provider.
- `icon` : The URL of the provider's icon. Optional.
2024-06-12 02:29:59 +02:00
## `Account`
2024-11-10 15:24:34 +01:00
Two extra attributes have been added to all returned [`Account` ](https://docs.joinmastodon.org/entities/Account/ ) objects.
2024-06-12 02:29:59 +02:00
2024-11-10 15:24:34 +01:00
This object is returned on routes such as `/api/v1/accounts/:id` , `/api/v1/accounts/verify_credentials` , etc.
2024-06-12 02:29:59 +02:00
```ts
2024-11-10 15:24:34 +01:00
type ExtendedAccount = Account & {
roles: Role[];
2024-07-17 14:02:29 +02:00
uri: string;
2024-06-12 02:29:59 +02:00
}
```
### `roles`
2024-11-10 15:24:34 +01:00
An array of [`Roles` ](./roles.md#role ) that the user has.
2024-06-14 10:19:15 +02:00
2024-07-17 14:02:29 +02:00
### `uri`
2024-11-10 15:24:34 +01:00
URI of the account's Versia entity (for federation). Similar to Mastodon's `uri` field on notes.
2024-07-17 14:02:29 +02:00
## `/api/v1/accounts/update_credentials`
2024-06-14 10:19:15 +02:00
The `username` parameter can now (optionally) be set to change the user's handle.
> [!WARNING]
> Clients should indicate to users that changing their handle will break existing links to their profile. This is reversible, but the old handle will be available for anyone to claim.
