API Gateway

API & Gateway

🌐 English · Deutsch

The bot side of the dashboard is a JSON-RPC 2.0 gateway provided by the pdc_webdashboard cog. The BFF is its only client: it connects over ${GATEWAY_URL}/rpc, authenticates with a shared token, and passes a verified user context that the gateway re-checks against Red's permissions on every call. This page documents the auth model, the parameter convention, the method namespaces and a representative method table. The methods listed here are confirmed from the cog's gateway/methods.py.

Transport & authentication

• Endpoint: HTTP POST to ${GATEWAY_URL}/rpc (a WebSocket /rpc is also defined for streaming; the web app uses HTTP). Default GATEWAY_URL is http://127.0.0.1:6970.
• Binding: the gateway listens on 127.0.0.1 only — not reachable from the network.
• Token: every request carries X-Dashboard-Token. The cog compares it with compare_digest (constant-time). Only the BFF knows the token (GATEWAY_TOKEN).
• User context: the BFF — which has already done the Discord OAuth2 login — passes the verified user. The gateway derives the user's level and enforces it.

Parameter convention

Every method receives params shaped like:

{
  "auth": { "user_id": "123", "guild_id": "456", "locale": "en-US" },
  "args": { /* method-specific arguments */ }
}

auth comes from the trusted BFF; args are the call's own parameters.

Permission gating

The gateway resolves the user's level (see Authentication) and checks the method's requirement before running it. Three extra rules apply:

• Guild floor. Any guild-scoped call requires at least guild_member, even if the contribution only asked for authenticated — this prevents a logged-in non-member from reading another server's data by manipulating guild_id.
• Lock. When the dashboard is locked, only the bot owner may run protected calls.
• Audit. Writing actions are recorded in the audit log (gateway.audit(...)), visible on the /audit page.

Method namespaces

Namespace	Purpose
core.*	Bot/guild info and the public command/stats overview.
dashboard.*	Branding, overview, settings, lock, sessions, custom pages.
manifest.*	Contribution manifest (permission-filtered).
widget.* / panel.* / page.* / list.*	Per-contribution data, forms and tables.
cogs.*	List and load/unload/reload cogs (owner).
slash.*	App-command listing, enable/disable, sync (owner).
downloader.*	Red Downloader: repos, update check, per-cog update/install/uninstall (owner).
settings.*	Red's bot settings, global and per guild.
serverstats.*	Statistics (needs the pdc_webdashboard_stats cog).
announce.*	Announcement channels + send.
system.*	Bot health/ops info (owner).
audit.*	Audit log (owner).
pages.*	Custom pages.

Representative methods

All names below are confirmed from gateway/methods.py.

Method	Min. level	Purpose
core.botinfo	authenticated	Name, id, avatar, guild count, latency, is-owner.
core.guilds	authenticated	Guilds the user can see (highest level per guild).
core.guild_detail	guild_member	Members, channels, roles, presence, dates.
core.commands	public	Active text + slash commands (no login).
core.stats	public	Public landing stats (no login).
dashboard.branding	public	Title/icon/theme + lock state (no login).
dashboard.overview	authenticated	Bot/gateway overview, is-owner.
dashboard.settings_get / dashboard.settings_set	bot_owner	Read/write branding.
dashboard.lock	bot_owner	Lock/unlock the dashboard.
dashboard.refresh_sessions	bot_owner	Bump the session epoch (invalidate all sessions).
dashboard.session_epoch	public	Current epoch (BFF session validation).
manifest.get	authenticated	Visible contributions, permission-filtered.
widget.data	per contribution	Data for one widget.
panel.schema / panel.submit	per contribution	Load / save a panel form.
list.rows / list.edit_form / list.edit / list.delete	per contribution	Manage a list.
page.schema	per contribution	A custom page's component tree.
cogs.list	bot_owner	Installed cogs with load state + repo.
cogs.set	bot_owner	load / unload / reload a cog.
slash.list	bot_owner	App commands grouped by cog (incl. disabled).
slash.set / slash.set_cog	bot_owner	Enable/disable a command or a whole cog.
slash.sync	bot_owner	Sync the command tree to Discord.
downloader.repos	bot_owner	Repos with installed + available cogs and update flags.
downloader.update_check	bot_owner	Update repos, report changed cogs.
downloader.cog_update	bot_owner	Update one cog, then reload + slash-sync.
downloader.cog_install / downloader.cog_uninstall	bot_owner	Install / uninstall a cog.
downloader.repo_add / downloader.repo_remove	bot_owner	Add / remove a repo.
settings.get / settings.set	guild_admin / bot_owner	Red settings (guild scope needs admin; global needs owner).
serverstats.overview	guild_member	Stats overview (needs pdc_webdashboard_stats).
serverstats.messages / .voice / .status / .invites / .activity / .commands	guild_member	Stats sections.
serverstats.member_drilldown / .channel_drilldown	guild_member	Per-member / per-channel detail.
announce.channels / announce.send	guild_admin	List sendable channels / send an announcement.
system.info	bot_owner	Uptime, latency, versions, memory, cog counts, gateway host/port.
audit.list	bot_owner	Audit log entries (newest first).
pages.list / pages.get	public	List / read custom pages (private enforced server-side).
pages.save / pages.delete	bot_owner	Create/update / delete a custom page.

Related pages

• Authentication — token + permission model
• Architecture — where the gateway sits in the request flow
• Cog Integration — the contribution methods (manifest/widget/panel/list)