Skip to main content
Documentation Powered by Redocly

Revolt API (0.6.1)

Download OpenAPI specification:Download

Revolt Support: contact@revolt.chat URL: https://revolt.chat License: AGPLv3 Terms of Service

Open source user-first chat platform.

Revolt Developer Documentation

Core

Query Node

Fetch the server configuration for this Revolt instance.

Responses

Response samples

Content type
application/json
{
  • "revolt": "string",
  • "features": {
    },
  • "ws": "string",
  • "app": "string",
  • "vapid": "string",
  • "build": {
    }
}

User Information

Fetch Self

Retrieve your user information.

Authorizations:
Session Token

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "username": "string",
  • "discriminator": "string",
  • "display_name": "string",
  • "avatar": {
    },
  • "relations": [
    ],
  • "badges": 0,
  • "status": {
    },
  • "profile": {
    },
  • "flags": 0,
  • "privileged": true,
  • "bot": {
    },
  • "relationship": "None",
  • "online": true
}

Fetch User

Retrieve a user's information.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "username": "string",
  • "discriminator": "string",
  • "display_name": "string",
  • "avatar": {
    },
  • "relations": [
    ],
  • "badges": 0,
  • "status": {
    },
  • "profile": {
    },
  • "flags": 0,
  • "privileged": true,
  • "bot": {
    },
  • "relationship": "None",
  • "online": true
}

Edit User

Edit currently authenticated user.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
Request Body schema: application/json
display_name
string or null [ 2 .. 32 ] characters ^[^\u200B\n\r]+$

New display name

avatar
string or null [ 1 .. 128 ] characters

Attachment Id for avatar

object or null

User's active status

object or null (Profile Data)

New user profile data

This is applied as a partial.

badges
integer or null <int32>

Bitfield of user badges

flags
integer or null <int32>

Enum of user flags

remove
Array of strings or null (FieldsUser) non-empty
Enum: "Avatar" "StatusText" "StatusPresence" "ProfileContent" "ProfileBackground" "DisplayName"

Fields to remove from user object

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "avatar": "string",
  • "status": {
    },
  • "profile": {
    },
  • "badges": 0,
  • "flags": 0,
  • "remove": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "username": "string",
  • "discriminator": "string",
  • "display_name": "string",
  • "avatar": {
    },
  • "relations": [
    ],
  • "badges": 0,
  • "status": {
    },
  • "profile": {
    },
  • "flags": 0,
  • "privileged": true,
  • "bot": {
    },
  • "relationship": "None",
  • "online": true
}

Fetch User Flags

Retrieve a user's flags.

path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "flags": 0
}

Change Username

Change your username.

Authorizations:
Session TokenSession Token
Request Body schema: application/json
username
required
string [ 2 .. 32 ] characters ^(\p{L}|[\d_.-])+$

New username

password
required
string [ 8 .. 1024 ] characters

Current account password

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "stringst"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "username": "string",
  • "discriminator": "string",
  • "display_name": "string",
  • "avatar": {
    },
  • "relations": [
    ],
  • "badges": 0,
  • "status": {
    },
  • "profile": {
    },
  • "flags": 0,
  • "privileged": true,
  • "bot": {
    },
  • "relationship": "None",
  • "online": true
}

Fetch Default Avatar

This returns a default avatar based on the given id.

path Parameters
target
required
string

Responses

Fetch User Profile

Retrieve a user's profile data.

Will fail if you do not have permission to access the other user's profile.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "content": "string",
  • "background": {
    }
}

Direct Messaging

Fetch Direct Message Channels

This fetches your direct messages, including any DM and group DM conversations.

Authorizations:
Session Token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Open Direct Message

Open a DM with another user.

If the target is oneself, a saved messages channel is returned.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "channel_type": "VoiceChannel",
  • "_id": "string",
  • "server": "string",
  • "name": "string",
  • "description": "string",
  • "icon": {
    },
  • "default_permissions": {
    },
  • "role_permissions": {
    },
  • "nsfw": true
}

Relationships

Fetch Mutual Friends And Servers

Retrieve a list of mutual friends and servers with another user.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "servers": [
    ]
}

Accept Friend Request

Accept another user's friend request.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "username": "string",
  • "discriminator": "string",
  • "display_name": "string",
  • "avatar": {
    },
  • "relations": [
    ],
  • "badges": 0,
  • "status": {
    },
  • "profile": {
    },
  • "flags": 0,
  • "privileged": true,
  • "bot": {
    },
  • "relationship": "None",
  • "online": true
}

Deny Friend Request / Remove Friend

Denies another user's friend request or removes an existing friend.

Authorizations:
Session Token
path Parameters
target
required
string

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "username": "string",
  • "discriminator": "string",
  • "display_name": "string",
  • "avatar": {
    },
  • "relations": [
    ],
  • "badges": 0,
  • "status": {
    },
  • "profile": {
    },
  • "flags": 0,
  • "privileged": true,
  • "bot": {
    },
  • "relationship": "None",
  • "online": true
}

Block User

Block another user by their id.

Authorizations:
Session Token
path Parameters
target
required
string

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "username": "string",
  • "discriminator": "string",
  • "display_name": "string",
  • "avatar": {
    },
  • "relations": [
    ],
  • "badges": 0,
  • "status": {
    },
  • "profile": {
    },
  • "flags": 0,
  • "privileged": true,
  • "bot": {
    },
  • "relationship": "None",
  • "online": true
}

Unblock User

Unblock another user by their id.

Authorizations:
Session Token
path Parameters
target
required
string

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "username": "string",
  • "discriminator": "string",
  • "display_name": "string",
  • "avatar": {
    },
  • "relations": [
    ],
  • "badges": 0,
  • "status": {
    },
  • "profile": {
    },
  • "flags": 0,
  • "privileged": true,
  • "bot": {
    },
  • "relationship": "None",
  • "online": true
}

Send Friend Request

Send a friend request to another user.

Authorizations:
Session Token
Request Body schema: application/json
username
required
string

Username and discriminator combo separated by #

Responses

Request samples

Content type
application/json
{
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "username": "string",
  • "discriminator": "string",
  • "display_name": "string",
  • "avatar": {
    },
  • "relations": [
    ],
  • "badges": 0,
  • "status": {
    },
  • "profile": {
    },
  • "flags": 0,
  • "privileged": true,
  • "bot": {
    },
  • "relationship": "None",
  • "online": true
}

Bots

Create Bot

Create a new Revolt bot.

Authorizations:
Session Token
Request Body schema: application/json
name
required
string [ 2 .. 32 ] characters ^(\p{L}|[\d_.-])+$

Bot username

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "owner": "string",
  • "token": "string",
  • "public": true,
  • "analytics": true,
  • "discoverable": true,
  • "interactions_url": "string",
  • "terms_of_service_url": "string",
  • "privacy_policy_url": "string",
  • "flags": 0
}

Fetch Public Bot

Fetch details of a public (or owned) bot by its id.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "username": "string",
  • "avatar": "string",
  • "description": "string"
}

Invite Bot

Invite a bot to a server or group by its id.`

Authorizations:
Session Token
path Parameters
target
required
string (Id)
Request Body schema: application/json
Any of
server
required
string

Server Id

Responses

Request samples

Content type
application/json
{
  • "group": "string"
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Fetch Bot

Fetch details of a bot you own by its id.

Authorizations:
Session Token
path Parameters
bot
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "bot": {
    },
  • "user": {
    }
}

Fetch Owned Bots

Fetch all of the bots that you have control over.

Authorizations:
Session Token

Responses

Response samples

Content type
application/json
{
  • "bots": [
    ],
  • "users": [
    ]
}

Delete Bot

Delete a bot by its id.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Edit Bot

Edit bot details by its id.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
Request Body schema: application/json
name
string or null [ 2 .. 32 ] characters ^(\p{L}|[\d_.-])+$

Bot username

public
boolean or null

Whether the bot can be added by anyone

analytics
boolean or null

Whether analytics should be gathered for this bot

Must be enabled in order to show up on Revolt Discover.

interactions_url
string or null [ 1 .. 2048 ] characters

Interactions URL

remove
Array of strings or null (FieldsBot) non-empty
Enum: "Token" "InteractionsURL"

Fields to remove from bot object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "public": true,
  • "analytics": true,
  • "interactions_url": "string",
  • "remove": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "owner": "string",
  • "token": "string",
  • "public": true,
  • "analytics": true,
  • "discoverable": true,
  • "interactions_url": "string",
  • "terms_of_service_url": "string",
  • "privacy_policy_url": "string",
  • "flags": 0
}

Channel Information

Fetch Channel

Fetch channel by its id.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "channel_type": "VoiceChannel",
  • "_id": "string",
  • "server": "string",
  • "name": "string",
  • "description": "string",
  • "icon": {
    },
  • "default_permissions": {
    },
  • "role_permissions": {
    },
  • "nsfw": true
}

Close Channel

Deletes a server channel, leaves a group or closes a group.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
query Parameters
leave_silently
boolean or null

Whether to not send a leave message

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Edit Channel

Edit a channel object by its id.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
Request Body schema: application/json
name
string or null [ 1 .. 32 ] characters

Channel name

description
string or null [ 0 .. 1024 ] characters

Channel description

owner
string or null

Group owner

icon
string or null [ 1 .. 128 ] characters

Icon

Provide an Autumn attachment Id.

nsfw
boolean or null

Whether this channel is age-restricted

archived
boolean or null

Whether this channel is archived

remove
Array of strings or null (FieldsChannel) non-empty
Enum: "Description" "Icon" "DefaultPermissions"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "owner": "string",
  • "icon": "string",
  • "nsfw": true,
  • "archived": true,
  • "remove": [
    ]
}

Response samples

Content type
application/json
{
  • "channel_type": "VoiceChannel",
  • "_id": "string",
  • "server": "string",
  • "name": "string",
  • "description": "string",
  • "icon": {
    },
  • "default_permissions": {
    },
  • "role_permissions": {
    },
  • "nsfw": true
}

Channel Invites

Create Invite

Creates an invite to this channel.

Channel must be a TextChannel.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "Group",
  • "_id": "string",
  • "creator": "string",
  • "channel": "string"
}

Channel Permissions

Set Role Permission

Sets permissions for the specified role in this channel.

Channel must be a TextChannel or VoiceChannel.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
role_id
required
string
Request Body schema: application/json
required
object

Representation of a single permission override

allow
required
integer <uint64> >= 0

Allow bit flags

deny
required
integer <uint64> >= 0

Disallow bit flags

Responses

Request samples

Content type
application/json
{
  • "permissions": {
    }
}

Response samples

Content type
application/json
{
  • "channel_type": "VoiceChannel",
  • "_id": "string",
  • "server": "string",
  • "name": "string",
  • "description": "string",
  • "icon": {
    },
  • "default_permissions": {
    },
  • "role_permissions": {
    },
  • "nsfw": true
}

Set Default Permission

Sets permissions for the default role in this channel.

Channel must be a Group, TextChannel or VoiceChannel.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
Request Body schema: application/json
Any of
permissions
required
integer <uint64> >= 0

Permission values to set for members in a Group

Responses

Request samples

Content type
application/json
{
  • "permissions": {
    }
}

Response samples

Content type
application/json
{
  • "channel_type": "VoiceChannel",
  • "_id": "string",
  • "server": "string",
  • "name": "string",
  • "description": "string",
  • "icon": {
    },
  • "default_permissions": {
    },
  • "role_permissions": {
    },
  • "nsfw": true
}

Messaging

Acknowledge Message

Lets the server and all other clients know that we've seen this message id in this channel.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
message
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Fetch Messages

Fetch multiple messages.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
query Parameters
limit
integer or null <int64> [ 1 .. 100 ]

Maximum number of messages to fetch

For fetching nearby messages, this is `(limit + 1)`.

before
string or null = 26 characters

Message id before which messages should be fetched

after
string or null = 26 characters

Message id after which messages should be fetched

sort
string (Message Sort)
Enum: "Relevance" "Latest" "Oldest"

Message sort direction

nearby
string or null = 26 characters

Message id to search around

Specifying 'nearby' ignores 'before', 'after' and 'sort'. It will also take half of limit rounded as the limits to each side. It also fetches the message ID specified.

include_users
boolean or null

Whether to include user (and member, if server channel) objects

Responses

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "users": [
    ],
  • "members": [
    ]
}

Send Message

Sends a message to the given channel.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
header Parameters
Idempotency-Key
string

Unique key to prevent duplicate requests

Request Body schema: application/json
nonce
string or null [ 1 .. 64 ] characters

Unique token to prevent duplicate message sending

This is deprecated and replaced by Idempotency-Key!

content
string or null [ 0 .. 2000 ] characters

Message content to send

attachments
Array of strings or null

Attachments to include in message

Array of objects or null (Reply)

Messages to reply to

Array of objects or null (SendableEmbed)

Embeds to include in message

Text embed content contributes to the content length cap

object or null

Name and / or avatar override information

object or null

Information to guide interactions on this message

Responses

Request samples

Content type
application/json
{
  • "nonce": "string",
  • "content": "string",
  • "attachments": [
    ],
  • "replies": [
    ],
  • "embeds": [
    ],
  • "masquerade": {
    },
  • "interactions": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "nonce": "string",
  • "channel": "string",
  • "author": "string",
  • "webhook": {
    },
  • "content": "string",
  • "system": {
    },
  • "attachments": [
    ],
  • "edited": "1970-01-01T00:00:00Z",
  • "embeds": [
    ],
  • "mentions": [
    ],
  • "replies": [
    ],
  • "reactions": {
    },
  • "interactions": {
    },
  • "masquerade": {
    }
}

Search for Messages

This route searches for messages within the given parameters.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
Request Body schema: application/json
query
required
string [ 1 .. 64 ] characters

Full-text search query

See MongoDB documentation for more information.

limit
integer or null <int64> [ 1 .. 100 ]

Maximum number of messages to fetch

before
string or null = 26 characters

Message id before which messages should be fetched

after
string or null = 26 characters

Message id after which messages should be fetched

sort
string (Message Sort)
Default: "Relevance"
Enum: "Relevance" "Latest" "Oldest"

Sort used for retrieving messages

include_users
boolean or null

Whether to include user (and member, if server channel) objects

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "limit": 1,
  • "before": "stringstringstringstringst",
  • "after": "stringstringstringstringst",
  • "sort": "Relevance",
  • "include_users": true
}

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "users": [
    ],
  • "members": [
    ]
}

Poll Message Changes

This route returns any changed message objects and tells you if any have been deleted.

Don't actually poll this route, instead use this to update your local database.

DEPRECATED

Authorizations:
Session Token
path Parameters
_target
required
string (Id)
Request Body schema: application/json
ids
required
Array of strings [ 0 .. 150 ] items

Array of message IDs

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Fetch Message

Retrieves a message by its id.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
msg
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "nonce": "string",
  • "channel": "string",
  • "author": "string",
  • "webhook": {
    },
  • "content": "string",
  • "system": {
    },
  • "attachments": [
    ],
  • "edited": "1970-01-01T00:00:00Z",
  • "embeds": [
    ],
  • "mentions": [
    ],
  • "replies": [
    ],
  • "reactions": {
    },
  • "interactions": {
    },
  • "masquerade": {
    }
}

Delete Message

Delete a message you've sent or one you have permission to delete.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
msg
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Edit Message

Edits a message that you've previously sent.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
msg
required
string (Id)
Request Body schema: application/json
content
string or null [ 1 .. 2000 ] characters

New message content

Array of objects or null (SendableEmbed) [ 0 .. 10 ] items

Embeds to include in the message

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "embeds": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "nonce": "string",
  • "channel": "string",
  • "author": "string",
  • "webhook": {
    },
  • "content": "string",
  • "system": {
    },
  • "attachments": [
    ],
  • "edited": "1970-01-01T00:00:00Z",
  • "embeds": [
    ],
  • "mentions": [
    ],
  • "replies": [
    ],
  • "reactions": {
    },
  • "interactions": {
    },
  • "masquerade": {
    }
}

Bulk Delete Messages

Delete multiple messages you've sent or one you have permission to delete.

This will always require ManageMessages permission regardless of whether you own the message or not.

Messages must have been sent within the past 1 week.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
Request Body schema: application/json
ids
required
Array of strings [ 1 .. 100 ] items

Message IDs

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Interactions

Add Reaction to Message

React to a given message.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
msg
required
string (Id)
emoji
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Remove Reaction(s) to Message

Remove your own, someone else's or all of a given reaction.

Requires ManageMessages if changing others' reactions.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
msg
required
string (Id)
emoji
required
string (Id)
query Parameters
user_id
string or null

Remove a specific user's reaction

remove_all
boolean or null

Remove all reactions

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Remove All Reactions from Message

Remove your own, someone else's or all of a given reaction.

Requires ManageMessages permission.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
msg
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Groups

Fetch Group Members

Retrieves all users who are part of this group.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Group

Create a new group channel.

Authorizations:
Session Token
Request Body schema: application/json
name
required
string [ 1 .. 32 ] characters

Group name

description
string or null [ 0 .. 1024 ] characters

Group description

users
required
Array of strings [ 0 .. 49 ] items

Array of user IDs to add to the group

Must be friends with these users.

nsfw
boolean or null

Whether this group is age-restricted

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "users": [
    ],
  • "nsfw": true
}

Response samples

Content type
application/json
{
  • "channel_type": "VoiceChannel",
  • "_id": "string",
  • "server": "string",
  • "name": "string",
  • "description": "string",
  • "icon": {
    },
  • "default_permissions": {
    },
  • "role_permissions": {
    },
  • "nsfw": true
}

Add Member to Group

Adds another user to the group.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
member
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Remove Member from Group

Removes a user from the group.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
member
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Voice

Join Call

Asks the voice server for a token to join the call.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "token": "string"
}

Webhooks

Creates a webhook

Creates a webhook which 3rd party platforms can use to send messages

Authorizations:
Session Token
path Parameters
target
required
string (Id)
Request Body schema: application/json
name
required
string [ 1 .. 32 ] characters
avatar
string or null [ 1 .. 128 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "avatar": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "avatar": {
    },
  • "channel_id": "string",
  • "token": "string"
}

Gets all webhooks

Gets all webhooks inside the channel

Authorizations:
Session Token
path Parameters
channel_id
required
string (Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Server Information

Create Server

Create a new server.

Authorizations:
Session Token
Request Body schema: application/json
name
required
string [ 1 .. 32 ] characters

Server name

description
string or null [ 0 .. 1024 ] characters

Server description

nsfw
boolean or null

Whether this server is age-restricted

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "nsfw": true
}

Response samples

Content type
application/json
{
  • "server": {
    },
  • "channels": [
    ]
}

Fetch Server

Fetch a server by its id.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
query Parameters
include_channels
boolean or null

Whether to include channels

Responses

Response samples

Content type
application/json
Example
{
  • "_id": "string",
  • "owner": "string",
  • "name": "string",
  • "description": "string",
  • "channels": [
    ],
  • "categories": [
    ],
  • "system_messages": {
    },
  • "roles": {
    },
  • "default_permissions": 0,
  • "icon": {
    },
  • "banner": {
    },
  • "flags": 0,
  • "nsfw": true,
  • "analytics": true,
  • "discoverable": true
}

Delete / Leave Server

Deletes a server if owner otherwise leaves.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
query Parameters
leave_silently
boolean or null

Whether to not send a leave message

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Edit Server

Edit a server by its id.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
Request Body schema: application/json
name
string or null [ 1 .. 32 ] characters

Server name

description
string or null [ 0 .. 1024 ] characters

Server description

icon
string or null

Attachment Id for icon

banner
string or null

Attachment Id for banner

Array of objects or null (Category)

Category structure for server

object or null

System message channel assignments

flags
integer or null <int32>

Bitfield of server flags

discoverable
boolean or null

Whether this server is public and should show up on Revolt Discover

analytics
boolean or null

Whether analytics should be collected for this server

Must be enabled in order to show up on Revolt Discover.

remove
Array of strings or null (FieldsServer) non-empty
Enum: "Description" "Categories" "SystemMessages" "Icon" "Banner"

Fields to remove from server object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "icon": "string",
  • "banner": "string",
  • "categories": [
    ],
  • "system_messages": {
    },
  • "flags": 0,
  • "discoverable": true,
  • "analytics": true,
  • "remove": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "owner": "string",
  • "name": "string",
  • "description": "string",
  • "channels": [
    ],
  • "categories": [
    ],
  • "system_messages": {
    },
  • "roles": {
    },
  • "default_permissions": 0,
  • "icon": {
    },
  • "banner": {
    },
  • "flags": 0,
  • "nsfw": true,
  • "analytics": true,
  • "discoverable": true
}

Mark Server As Read

Mark all channels in a server as read.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Create Channel

Create a new Text or Voice channel.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
Request Body schema: application/json
type
string (Channel Type)
Default: "Text"
Enum: "Text" "Voice"

Channel type

name
required
string [ 1 .. 32 ] characters

Channel name

description
string or null [ 0 .. 1024 ] characters

Channel description

nsfw
boolean or null

Whether this channel is age restricted

Responses

Request samples

Content type
application/json
{
  • "type": "Text",
  • "name": "string",
  • "description": "string",
  • "nsfw": true
}

Response samples

Content type
application/json
{
  • "channel_type": "VoiceChannel",
  • "_id": "string",
  • "server": "string",
  • "name": "string",
  • "description": "string",
  • "icon": {
    },
  • "default_permissions": {
    },
  • "role_permissions": {
    },
  • "nsfw": true
}

Server Members

Fetch Members

Fetch all server members.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
query Parameters
exclude_offline
boolean or null

Whether to exclude offline users

Responses

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "users": [
    ]
}

Fetch Member

Retrieve a member.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
member
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "_id": {
    },
  • "joined_at": "1970-01-01T00:00:00Z",
  • "nickname": "string",
  • "avatar": {
    },
  • "roles": [
    ],
  • "timeout": "1970-01-01T00:00:00Z"
}

Kick Member

Removes a member from the server.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
member
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Edit Member

Edit a member by their id.

Authorizations:
Session Token
path Parameters
server
required
string (Id)
target
required
string (Id)
Request Body schema: application/json
nickname
string or null [ 1 .. 32 ] characters

Member nickname

avatar
string or null

Attachment Id to set for avatar

roles
Array of strings or null

Array of role ids

timeout
string or null <date-time>

ISO8601 formatted timestamp

remove
Array of strings or null (FieldsMember) non-empty
Enum: "Nickname" "Avatar" "Roles" "Timeout"

Fields to remove from channel object

Responses

Request samples

Content type
application/json
{
  • "nickname": "string",
  • "avatar": "string",
  • "roles": [
    ],
  • "timeout": "1970-01-01T00:00:00Z",
  • "remove": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": {
    },
  • "joined_at": "1970-01-01T00:00:00Z",
  • "nickname": "string",
  • "avatar": {
    },
  • "roles": [
    ],
  • "timeout": "1970-01-01T00:00:00Z"
}

Query members by name

Query members by a given name, this API is not stable and will be removed in the future.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
query Parameters
query
required
string

String to search for

experimental_api
required
boolean

Discourage use of this API

Responses

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "users": [
    ]
}

Ban User

Ban a user by their id.

Authorizations:
Session Token
path Parameters
server
required
string (Id)
target
required
string (Id)
Request Body schema: application/json
reason
string or null [ 1 .. 1024 ] characters

Ban reason

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "_id": {
    },
  • "reason": "string"
}

Unban user

Remove a user's ban.

Authorizations:
Session Token
path Parameters
server
required
string (Id)
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Fetch Bans

Fetch all bans on a server.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "bans": [
    ]
}

Fetch Invites

Fetch all server invites.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Server Permissions

Create Role

Creates a new server role.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
Request Body schema: application/json
name
required
string [ 1 .. 32 ] characters

Role name

rank
integer or null <int64>

Ranking position

Smaller values take priority.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "rank": 0
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "role": {
    }
}

Delete Role

Delete a server role by its id.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
role_id
required
string

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Edit Role

Edit a role by its id.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
role_id
required
string
Request Body schema: application/json
name
string or null [ 1 .. 32 ] characters

Role name

colour
string or null [ 1 .. 128 ] characters (?i)^(?:[a-z ]+|var\(--[a-z\d-]+\)|rgba?\([\d...

Role colour

hoist
boolean or null

Whether this role should be displayed separately

rank
integer or null <int64>

Ranking position

Smaller values take priority.

remove
Array of strings or null (FieldsRole) non-empty
Value: "Colour"

Fields to remove from role object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "colour": "string",
  • "hoist": true,
  • "rank": 0,
  • "remove": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "permissions": {
    },
  • "colour": "string",
  • "hoist": true,
  • "rank": 0
}

Set Role Permission

Sets permissions for the specified role in the server.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
role_id
required
string
Request Body schema: application/json
required
object

Representation of a single permission override

allow
required
integer <uint64> >= 0

Allow bit flags

deny
required
integer <uint64> >= 0

Disallow bit flags

Responses

Request samples

Content type
application/json
{
  • "permissions": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "owner": "string",
  • "name": "string",
  • "description": "string",
  • "channels": [
    ],
  • "categories": [
    ],
  • "system_messages": {
    },
  • "roles": {
    },
  • "default_permissions": 0,
  • "icon": {
    },
  • "banner": {
    },
  • "flags": 0,
  • "nsfw": true,
  • "analytics": true,
  • "discoverable": true
}

Set Default Permission

Sets permissions for the default role in this server.

Authorizations:
Session Token
path Parameters
target
required
string (Id)
Request Body schema: application/json
permissions
required
integer <uint64> >= 0

Responses

Request samples

Content type
application/json
{
  • "permissions": 0
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "owner": "string",
  • "name": "string",
  • "description": "string",
  • "channels": [
    ],
  • "categories": [
    ],
  • "system_messages": {
    },
  • "roles": {
    },
  • "default_permissions": 0,
  • "icon": {
    },
  • "banner": {
    },
  • "flags": 0,
  • "nsfw": true,
  • "analytics": true,
  • "discoverable": true
}

Invites

Fetch Invite

Fetch an invite by its id.

path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "Group",
  • "code": "string",
  • "channel_id": "string",
  • "channel_name": "string",
  • "channel_description": "string",
  • "user_name": "string",
  • "user_avatar": {
    }
}

Join Invite

Join an invite by its ID.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "Server",
  • "channels": [
    ],
  • "server": {
    }
}

Delete Invite

Delete an invite by its id.

Authorizations:
Session Token
path Parameters
target
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Emojis

Fetch Emoji

Fetch an emoji by its id.

Authorizations:
Session Token
path Parameters
id
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "parent": {
    },
  • "creator_id": "string",
  • "name": "string",
  • "animated": true,
  • "nsfw": true
}

Create New Emoji

Create an emoji by its Autumn upload id.

Authorizations:
Session Token
path Parameters
id
required
string
Request Body schema: application/json
name
required
string [ 1 .. 32 ] characters ^[a-z0-9_]+$

Server name

required
object or object

Information about what owns this emoji

nsfw
boolean
Default: false

Whether the emoji is mature

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "parent": {
    },
  • "nsfw": false
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "parent": {
    },
  • "creator_id": "string",
  • "name": "string",
  • "animated": true,
  • "nsfw": true
}

Delete Emoji

Delete an emoji by its id.

Authorizations:
Session Token
path Parameters
id
required
string (Id)

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Admin

Query Stats

Fetch various technical statistics.

Responses

Response samples

Content type
application/json
{
  • "indices": {
    },
  • "coll_stats": {
    }
}

Globally Fetch Messages

This is a privileged route to globally fetch messages.

Authorizations:
Session Token
Request Body schema: application/json
Any of
nearby
required
string

Message id to search around

Specifying 'nearby' ignores 'before', 'after' and 'sort'. It will also take half of limit rounded as the limits to each side. It also fetches the message ID specified.

limit
integer or null <int64>

Maximum number of messages to fetch

For fetching nearby messages, this is `(limit + 1)`.

channel
string or null

Parent channel ID

author
string or null

Message author ID

query
string or null

Search query

Responses

Request samples

Content type
application/json
{
  • "before": "string",
  • "after": "string",
  • "sort": "Relevance",
  • "limit": 0,
  • "channel": "string",
  • "author": "string",
  • "query": "string"
}

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "users": [
    ],
  • "members": [
    ]
}

User Safety

Edit Report

Edit a report.

Authorizations:
Session Token
path Parameters
report
required
string (Id)
Request Body schema: application/json
(object or null) or (object or null) or (object or null)

Status of the report

notes
string or null

Report notes

Responses

Request samples

Content type
application/json
{
  • "status": {
    },
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "status": "Resolved",
  • "closed_at": "1970-01-01T00:00:00Z",
  • "_id": "string",
  • "author_id": "string",
  • "content": {
    },
  • "additional_context": "string",
  • "notes": ""
}

Fetch Report

Fetch a report by its ID

Authorizations:
Session Token
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "Resolved",
  • "closed_at": "1970-01-01T00:00:00Z",
  • "_id": "string",
  • "author_id": "string",
  • "content": {
    },
  • "additional_context": "string",
  • "notes": ""
}

Fetch Reports

Fetch all available reports

Authorizations:
Session Token
query Parameters
content_id
string or null

Find reports against messages, servers, or users

author_id
string or null

Find reports created by user

status
string (ReportStatusString)
Enum: "Created" "Rejected" "Resolved"

Report status to include in search

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Report Content

Report a piece of content to the moderation team.

Authorizations:
Session Token
Request Body schema: application/json
required
object or object or object

The content being reported

additional_context
string [ 0 .. 1000 ] characters
Default: ""

Additional report description

Responses

Request samples

Content type
application/json
{
  • "content": {
    },
  • "additional_context": ""
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Fetch Snapshots

Fetch a snapshots for a given report

Authorizations:
Session Token
path Parameters
report_id
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Strike

Create a new account strike

Authorizations:
Session Token
Request Body schema: application/json
user_id
required
string

Id of reported user

reason
required
string

Attached reason

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "user_id": "string",
  • "reason": "string"
}

Fetch Strikes

Fetch strikes for a user by their ID

Authorizations:
Session Token
path Parameters
user_id
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Edit Strike

Edit a strike by its ID

Authorizations:
Session Token
path Parameters
strike_id
required
string
Request Body schema: application/json
reason
required
string

New attached reason

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Delete Strike

Delete a strike by its ID

Authorizations:
Session Token
path Parameters
strike_id
required
string

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Account

Create Account

Create a new account.

Request Body schema: application/json
email
required
string

Valid email address

password
required
string

Password

invite
string or null

Invite code

captcha
string or null

Captcha verification code

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string",
  • "invite": "string",
  • "captcha": "string"
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Resend Verification

Resend account creation verification email.

Request Body schema: application/json
email
required
string

Email associated with the account

captcha
string or null

Captcha verification code

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "captcha": "string"
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Confirm Account Deletion

Schedule an account for deletion by confirming the received token.

Request Body schema: application/json
token
required
string

Deletion token

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Delete Account

Request to have an account deleted.

Authorizations:
Valid MFA TicketSession Token

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Fetch Account

Fetch account information from the current session.

Authorizations:
Session Token

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "email": "string"
}

Disable Account

Disable an account.

Authorizations:
Valid MFA TicketSession Token

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Change Password

Change the current account password.

Authorizations:
Session Token
Request Body schema: application/json
password
required
string

New password

current_password
required
string

Current password

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "current_password": "string"
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Change Email

Change the associated account email.

Authorizations:
Session Token
Request Body schema: application/json
email
required
string

Valid email address

current_password
required
string

Current password

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "current_password": "string"
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Verify Email

Verify an email address.

path Parameters
code
required
string

Responses

Response samples

Content type
application/json
{
  • "ticket": {
    }
}

Send Password Reset

Send an email to reset account password.

Request Body schema: application/json
email
required
string

Email associated with the account

captcha
string or null

Captcha verification code

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "captcha": "string"
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Password Reset

Confirm password reset and change the password.

Request Body schema: application/json
token
required
string

Reset token

password
required
string

New password

remove_sessions
boolean
Default: false

Whether to logout all sessions

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "password": "string",
  • "remove_sessions": false
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Session

Login

Login to an account.

Request Body schema: application/json
Any of
email
required
string

Email

password
required
string

Password

friendly_name
string or null

Friendly name used for the session

Responses

Request samples

Content type
application/json
{
  • "mfa_ticket": "string",
  • "mfa_response": {
    },
  • "friendly_name": "string"
}

Response samples

Content type
application/json
{
  • "result": "Disabled",
  • "user_id": "string"
}

Logout

Delete current session.

Authorizations:
Session Token

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Fetch Sessions

Fetch all sessions associated with this account.

Authorizations:
Session Token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete All Sessions

Delete all active sessions, optionally including current one.

Authorizations:
Session TokenSession Token
query Parameters
revoke_self
boolean or null

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Revoke Session

Delete a specific active session.

Authorizations:
Session Token
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Edit Session

Edit current session information.

Authorizations:
Session Token
path Parameters
id
required
string
Request Body schema: application/json
friendly_name
required
string

Session friendly name

Responses

Request samples

Content type
application/json
{
  • "friendly_name": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string"
}

Onboarding

Check Onboarding Status

This will tell you whether the current account requires onboarding or whether you can continue to send requests as usual. You may skip calling this if you're restoring an existing session.

Authorizations:
Session TokenSession Token

Responses

Response samples

Content type
application/json
{
  • "onboarding": true
}

Complete Onboarding

This sets a new username, completes onboarding and allows a user to start using Revolt.

Authorizations:
Session TokenSession Token
Request Body schema: application/json
username
required
string [ 2 .. 32 ] characters ^(\p{L}|[\d_.-])+$

New username which will be used to identify the user on the platform

Responses

Request samples

Content type
application/json
{
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

MFA

Create MFA ticket

Create a new MFA ticket or validate an existing one.

Authorizations:
Session TokenUnvalidated MFA Ticket
Request Body schema: application/json
Any of
password
required
string

Responses

Request samples

Content type
application/json
{
  • "totp_code": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "account_id": "string",
  • "token": "string",
  • "validated": true,
  • "authorised": true,
  • "last_totp_code": "string"
}

MFA Status

Fetch MFA status of an account.

Authorizations:
Session Token

Responses

Response samples

Content type
application/json
{
  • "email_otp": true,
  • "trusted_handover": true,
  • "email_mfa": true,
  • "totp_mfa": true,
  • "security_key_mfa": true,
  • "recovery_active": true
}

Fetch Recovery Codes

Fetch recovery codes for an account.

Authorizations:
Valid MFA TicketSession Token

Responses

Response samples

Content type
application/json
[
  • "string"
]

Generate Recovery Codes

Re-generate recovery codes for an account.

Authorizations:
Valid MFA TicketSession Token

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get MFA Methods

Fetch available MFA methods.

Authorizations:
Session Token

Responses

Response samples

Content type
application/json
[
  • "Password"
]

Enable TOTP 2FA

Generate a new secret for TOTP.

Authorizations:
Session Token
Request Body schema: application/json
Any of
password
required
string

Responses

Request samples

Content type
application/json
{
  • "totp_code": "string"
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Generate TOTP Secret

Generate a new secret for TOTP.

Authorizations:
Valid MFA TicketSession Token

Responses

Response samples

Content type
application/json
{
  • "secret": "string"
}

Disable TOTP 2FA

Disable TOTP 2FA for an account.

Authorizations:
Valid MFA TicketSession Token

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Sync

Fetch Settings

Fetch settings from server filtered by keys.

This will return an object with the requested keys, each value is a tuple of (timestamp, value), the value is the previously uploaded data.

Authorizations:
Session Token
Request Body schema: application/json
keys
required
Array of strings

Keys to fetch

Responses

Request samples

Content type
application/json
{
  • "keys": [
    ]
}

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

Set Settings

Upload data to save to settings.

Authorizations:
Session Token
query Parameters
timestamp
integer or null <int64>

Timestamp of settings change.

Used to avoid feedback loops.

Request Body schema: application/json
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Fetch Unreads

Fetch information about unread state on channels.

Authorizations:
Session Token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Web Push

Push Subscribe

Create a new Web Push subscription.

If an existing subscription exists on this session, it will be removed.

Authorizations:
Session Token
Request Body schema: application/json
endpoint
required
string
p256dh
required
string
auth
required
string

Responses

Request samples

Content type
application/json
{
  • "endpoint": "string",
  • "p256dh": "string",
  • "auth": "string"
}

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}

Unsubscribe

Remove the Web Push subscription associated with the current session.

Authorizations:
Session Token

Responses

Response samples

Content type
application/json
{
  • "type": "FailedValidation"
}