API Reference

Aquarium provides a REST API for programmatic access to server and user data.

The API is primarily for internal dashboard use. Public API access may be limited. Contact us for developer access.

Authentication

All API requests require authentication via Discord OAuth session cookies.

Cookie: connect.sid=<session_id>

Base URL

https://api.aquarium.example.com

Endpoints

Auth

Get Current User

GET /api/auth/me

Returns the authenticated user and their subscription status.

Response:

{
  "user": {
    "id": "123456789",
    "username": "example",
    "avatar": "abc123"
  },
  "subscription": {
    "tier": "pro",
    "expiresAt": "2024-12-31T00:00:00Z"
  }
}

Guilds

List User's Guilds

GET /api/guilds

Returns guilds where the user and bot are both members.

Get Guild Overview

GET /api/admin/guilds/:guildId/overview

Returns complete guild information including immersion status.

Immersion

Get Immersion Status

GET /api/immersion/guilds/:guildId/status

Setup Immersion

POST /api/immersion/guilds/:guildId/setup

Body:

{
  "categoryId": "optional-category-id"
}

Update Enabled Languages

PATCH /api/immersion/guilds/:guildId/settings/languages

Body:

{
  "enabledLanguages": ["EN", "ES", "FR"]
}

Reset Immersion

DELETE /api/immersion/guilds/:guildId?deleteChannels=true

Moderation

Get Ban Status

GET /api/moderation/guilds/:guildId/members/:userId/ban

Ban User

POST /api/moderation/guilds/:guildId/members/:userId/ban

Body:

{
  "reason": "Spam",
  "duration": "7d"
}

Unban User

DELETE /api/moderation/guilds/:guildId/members/:userId/ban

Warn User

POST /api/moderation/guilds/:guildId/members/:userId/warn

Body:

{
  "reason": "Off-topic messages"
}

Get Warnings

GET /api/moderation/guilds/:guildId/members/:userId/warnings

Get Moderation History

GET /api/moderation/guilds/:guildId/members/:userId/history

Members

List Guild Members

GET /api/admin/guilds/:guildId/members?page=1&limit=20&search=query

Update Member

PATCH /api/admin/guilds/:guildId/members/:userId

Body:

{
  "showOnLeaderboard": false,
  "subscribedLanguages": ["EN", "ES"]
}

Analytics

Get Guild Analytics

GET /api/admin/guilds/:guildId/analytics?days=30

Error Responses

All errors follow this format:

{
  "error": "Error message here"
}

Status Codes

Code	Meaning
200	Success
400	Bad request
401	Unauthorized
403	Forbidden
404	Not found
500	Server error

Rate Limits

Standard endpoints: 60 requests/minute
Setup/mutation endpoints: 10 requests/minute

Exceeding limits returns 429 Too Many Requests.

API Reference

On this page