Astral API Docs | Astral Developer Documentation

🇬🇧 English · 🇷🇺 Русская версия →

Welcome to the Astral developer documentation. Everything here describes the public developer-facing API: the same endpoints external bots, OAuth2 integrations and webhook senders use to talk to Astral.

AI Assistant

Can't find what you need? Ask the AI assistant → — it knows the entire documentation.

What you can build

Bots — messages, slash commands, voice events, Gateway dispatches in real time.
Webhooks — GitHub, CI, monitoring post into channels without a long-lived process.
OAuth2 integrations — users link their Astral identity to your app.
Automations — REST for reads, Gateway for events.

Pick a starting point

You want to…	Open
Get a working bot in 5 minutes	Quickstart
Understand the bot model end to end	Bot API Guide
Look up an endpoint	API Reference
Subscribe to live events	Gateway and Gateway Events
Understand permissions	Permissions
Understand rate limits	Rate limits
Register slash commands	Application Commands
Diagnose a broken bot	Troubleshooting
Set up OAuth2	OAuth2 Guide
Self-host Astral	Self-Hosting
Pick a client library	Libraries

Getting your first bot token

Open the Astral client at astraof.com.
Open User Settings → Applications (the </> icon in the user-settings sidebar).
Click Create Application and give it a name.
Open the new application, switch to the Bot section, and copy the bot token.

Then follow the Quickstart — it walks through environment setup, the three sanity-check requests every bot should pass, and a minimal ping → pong example using only the ws package from npm.

Treat bot tokens like passwords

A leaked bot token is equivalent to handing over the bot's account. Do not commit tokens to Git, do not embed them in browser bundles, and rotate them through POST /oauth2/applications/:id/bot/reset-token if you suspect compromise.

Base URLs

Astral runs on the official deployment at:

HTTP API: https://astraof.com/api/v1
Gateway:  wss://astraof.com/gateway?v=1&encoding=json

If you're targeting a self-hosted Astral instance, replace astraof.com with your own domain — the API surface and event names are identical.

Authentication for bots

Authorization: Bot YOUR_BOT_TOKEN

The Bot prefix is required. Bots send the same Authorization header on every REST call and on the Gateway IDENTIFY payload.

Bots and the origin gate

Astral's production API gates non-GET, cookie-only requests by Origin. Bots are immune — as soon as you set Authorization: Bot <token>, the origin check is bypassed and your request is judged by the token alone. You do not need to send an Origin header from your bot.

Need help?

Open the in-app support channel from User Settings → Help.
Email the product team at product@astraof.com.
File a bug or feature request through the support channel — please include your application id, the request-id header from a failing response, and a minimal reproduction.

Happy building.