Revolt Getting Started: Account, Keys, and First API Request (2026)

Getting started overview

Revolt is an open-source, privacy-focused communication platform designed for communities. For developers, Revolt provides an extensive API that facilitates the creation of bots, custom integrations, and even alternative clients. This guide focuses on the foundational steps required to begin interacting with the Revolt API: account creation, obtaining necessary credentials, and executing a basic API call.

The Revolt API is primarily HTTP-based, utilizing JSON for request and response bodies. Authentication for bots typically involves a bot token, which acts as a bearer token in the x-bot-token header. This structure is common among many web APIs, including those for other communication platforms and financial services, which often rely on similar token-based authentication methods to secure access to resources, as detailed in RFC 6750 for OAuth 2.0 Bearer Token Usage.

Before making your first API request, you will need:

• A Revolt user account.
• An application (bot) created within your account.
• The bot token associated with your application.
• A client or tool capable of making HTTP requests (e.g., cURL, Postman, a programming language's HTTP library).

Create an account and get keys

To interact with the Revolt API, you first need a Revolt user account. If you haven't already, register for an account on the Revolt homepage. Once registered and logged in, you'll proceed to create a bot application and obtain its unique token.

Account Registration

1. Navigate to the Revolt website.
2. Click on the "Register" button or equivalent prompt.
3. Follow the on-screen instructions to create your account, which typically involves providing an email, username, and password.
4. Verify your email address if prompted.

Creating a Bot Application and Obtaining a Token

Revolt bot tokens are essential for authenticating your bot's requests to the API. Each bot has a unique token that should be kept confidential.

1. Log in to your Revolt account.
2. Access the developer dashboard or bot creation page within the Revolt client or web interface. Specific navigation paths may vary slightly with platform updates, but typically this is found under user settings or developer options.
3. Click on "Create New Bot" or a similar option.
4. Provide a name for your bot.
5. Once the bot is created, you will be presented with its details, including the bot token. This token is usually a long alphanumeric string.
6. Copy this token immediately and store it securely. You may not be able to view it again after leaving the page without regenerating it.

Your first request

With your bot token in hand, you can now attempt your first API request. A common initial request is to fetch information about the bot itself or to list the servers it is a member of. We will use the GET /bots/@me endpoint, which returns information about the authenticated bot.

API Endpoint Details

• Method: GET
• Endpoint: https://api.revolt.chat/bots/@me
• Authentication: x-bot-token: YOUR_BOT_TOKEN in the request header.

Example using cURL

cURL is a command-line tool and library for transferring data with URLs, commonly used for testing API endpoints. Replace YOUR_BOT_TOKEN with the actual token you obtained.

curl -X GET \
  https://api.revolt.chat/bots/@me \
  -H "x-bot-token: YOUR_BOT_TOKEN"
    

Expected Response

A successful response will return a JSON object containing details about your bot, similar to this structure (values will differ):

{
  "_id": "61e2f...",
  "owner": "61e2f...",
  "token": "redacted_token",
  "public": false,
  "interactions": {
    "enabled": false
  },
  "username": "MyFirstRevoltBot",
  "avatar": null,
  "badges": 0,
  "bot": {
    "owner": "61e2f..."
  },
  "relationship": "None",
  "online": true,
  "flags": 0
}
    

If you receive a similar JSON response, your bot token is valid, and you have successfully made your first authenticated request to the Revolt API.

Common next steps

After successfully making your first API call, you can explore more advanced functionalities. Here are some common next steps for Revolt API developers:

• Read the API Documentation: The Revolt API reference is comprehensive and covers all available endpoints, request/response formats, and authentication methods.
• Join a Server: To make your bot interact with users, you'll need to invite it to a Revolt server. Bots require specific permissions to perform actions like sending messages or managing channels.
• Implement Webhooks: For real-time updates and event-driven programming, familiarize yourself with Revolt's webhook capabilities, which allow your application to receive notifications about events on the platform. Many APIs, such as Stripe's webhook implementation, follow similar security and delivery patterns.
• Explore SDKs (if available): While Revolt's official documentation does not list specific SDKs, the open-source nature of the project means community-developed libraries might exist in your preferred programming language. These SDKs can abstract away raw HTTP requests, simplifying development.
• Error Handling: Implement robust error handling in your code to gracefully manage API rate limits, invalid tokens, or malformed requests. The Revolt API returns standard HTTP status codes and JSON error bodies.
• Build Advanced Features: Start developing features such as automated messaging, moderation tools, or data retrieval from Revolt servers.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some steps to troubleshoot problems:

• Check Bot Token: Ensure your x-bot-token header contains the exact and complete bot token. Any typo or missing character will lead to authentication failure.
• Verify Endpoint URL: Double-check the API endpoint URL for correctness. A common mistake is using an incorrect base URL or path. The official Revolt API documentation always lists the correct endpoints.
• Inspect HTTP Status Codes:
• 401 Unauthorized: Indicates an issue with your authentication token. Ensure it's correct and properly formatted in the x-bot-token header.
• 403 Forbidden: Your bot may lack the necessary permissions to access the requested resource. Check your bot's permissions on the Revolt platform.
• 404 Not Found: The endpoint you're trying to reach does not exist, or the resource you're requesting (e.g., a specific channel ID) cannot be found.
• 429 Too Many Requests: You have hit a rate limit. Implement backoff strategies or wait before retrying.
• Examine Response Body: The API often provides detailed error messages in the JSON response body. Parse and read these messages for specific clues about what went wrong.
• Network Connectivity: Ensure your local machine has stable internet access and is not blocked by a firewall from reaching api.revolt.chat.
• Consult Revolt Documentation and Community: The Revolt documentation is a primary resource. You can also engage with the Revolt developer community for assistance.

Quick Reference for Getting Started