API Reference

Complete API documentation for api.lyx.lol. All endpoints require authentication unless noted.

Authentication

The Lyx API uses session-based authentication via secure, HTTP-only cookies. All authenticated requests must include the session cookie.

Obtaining a Session

Redirect user to GET /v1/auth/discord
User authorizes on Discord
Discord redirects to /v1/auth/discord/callback with code
Backend exchanges code for tokens, creates session
Session cookie lyx_session set on response

Using the Session

Include the cookie in all authenticated requests:

Cookie: lyx_session=abc123...

Or use credentials: 'include' in fetch:

fetch('https://api.lyx.lol/v1/user/me', { credentials: 'include' })

Session Expiry

Sessions expire after 30 days of inactivity. Refresh by re-authenticating.

Base URL

All endpoints are under:

https://api.lyx.lol/v1

Example: GET https://api.lyx.lol/v1/guilds/123456789/settings

Rate Limits

API endpoints are rate limited per session:

Endpoint Type	Limit	Window
Read (GET)	120 requests	60 seconds
Write (POST/PUT/DELETE)	30 requests	60 seconds
Bulk operations	5 requests	60 seconds
Auth endpoints	10 requests	60 seconds

Rate limit headers included in responses:

X-RateLimit-Limit — max requests
X-RateLimit-Remaining — remaining
X-RateLimit-Reset — Unix timestamp

On 429: wait for Retry-After seconds.

Error Codes

All errors follow a consistent format:

{
  "error": "error_code",
  "message": "Human-readable description",
  "details": {}
}

Code	HTTP	Description
`unauthorized`	401	Invalid or missing session
`forbidden`	403	Insufficient permissions
`not_found`	404	Resource not found
`validation_error`	422	Invalid request body
`rate_limited`	429	Too many requests
`internal_error`	500	Server error
`maintenance`	503	Service in maintenance
`guild_not_found`	404	Guild not in database
`bot_not_in_guild`	400	Lyx not in target server
`missing_permissions`	403	Bot lacks required Discord permissions
`hierarchy_error`	400	Role hierarchy violation

Health & Status

GET /health

Basic health check. No auth required.

Response: { "status": "ok", "timestamp": 1699900000000 }

GET /v1/bot/info

Bot information.

Response: { "name": "Lyx", "version": "1.0.0", "uptime": 3600000, "guilds": 1500, "users": 500000, "latency": 45 }

GET /v1/bot/status

Detailed service status.

Response: { "bot": "operational", "api": "operational", "database": "operational", "discord": "operational", "lastIncident": null }

GET /v1/bot/commands

List all registered slash commands.

Response: { "commands": [{ "name": "ban", "description": "Ban a member", "options": [...] }] }

Authentication Endpoints

GET /v1/auth/discord

Initiate Discord OAuth2 flow. Redirects to Discord.

GET /v1/auth/discord/callback

OAuth2 callback. Exchanges code for session. Sets lyx_session cookie.

POST /v1/auth/logout

Destroy current session.

Response: { "ok": true }

GET /v1/auth/me

Get current authenticated user.

Response: { "user": { "id": "123", "username": "User", "avatar": "abc", "discriminator": "0" }, "guilds": [...] }

User Endpoints

GET /v1/users/@me

Current user profile.

Response: { "id": "123", "username": "User", "avatar": "abc", "discriminator": "0", "created_at": "2020-01-01T00:00:00Z" }

GET /v1/users/@me/guilds

Servers where user has Manage Server + Lyx installed.

Response: { "guilds": [{ "id": "456", "name": "My Server", "icon": "abc", "owner": true, "permissions": "2147483647", "member_count": 1000, "features": ["COMMUNITY"] }] }

Guild Endpoints

GET /v1/guilds/:guildId

Get guild info.

GET /v1/guilds/:guildId/settings

Get all guild settings.

PATCH /v1/guilds/:guildId/settings

Update guild settings. Body: partial settings object.

GET /v1/guilds/:guildId/channels

List channels (for selectors).

GET /v1/guilds/:guildId/roles

List roles (for selectors).

GET /v1/guilds/:guildId/members

List members (paginated). Query: ?limit=50&after=123

Moderation Endpoints

GET /v1/guilds/:guildId/moderation/cases

List cases. Query: ?limit=25&page=1&action=ban&user_id=123&from=2025-01-01&to=2025-12-31

GET /v1/guilds/:guildId/moderation/cases/:caseId

Get single case details.

POST /v1/guilds/:guildId/moderation/cases

Create moderation case. Body:

{
  "action": "ban|kick|timeout|warn|purge|lock|unlock",
  "target_id": "123",
  "reason": "Reason",
  "duration": 60, // for timeout
  "delete_message_days": 1, // for ban
  "amount": 50, // for purge
  "channel_id": "456" // for lock/unlock
}

GET /v1/guilds/:guildId/moderation/stats

Moderation statistics. Query: ?days=30&user_id=123

GET /v1/guilds/:guildId/moderation/warnings

List user warnings.

POST /v1/guilds/:guildId/moderation/warnings

Issue warning. Body: { "target_id": "123", "reason": "Reason", "dm": true }

DELETE /v1/guilds/:guildId/moderation/warnings/:warningId

Remove specific warning.

DELETE /v1/guilds/:guildId/moderation/warnings/user/:userId

Clear all warnings for user.

Auto-Moderation Endpoints

GET /v1/guilds/:guildId/automod

Get automod configuration.

PATCH /v1/guilds/:guildId/automod

Update automod settings. Body: partial config.

GET /v1/guilds/:guildId/automod/rules

List all rules.

POST /v1/guilds/:guildId/automod/rules

Create rule. Body: rule config.

PATCH /v1/guilds/:guildId/automod/rules/:ruleId

Update rule.

DELETE /v1/guilds/:guildId/automod/rules/:ruleId

Delete rule.

GET /v1/guilds/:guildId/automod/exemptions

List exempt roles/channels.

POST /v1/guilds/:guildId/automod/exemptions

Add exemption. Body: { "type": "role|channel", "target_id": "123" }

DELETE /v1/guilds/:guildId/automod/exemptions/:type/:targetId

Remove exemption.

GET /v1/guilds/:guildId/automod/events

Recent automod events. Query: ?limit=50

Welcome/Goodbye Endpoints

GET /v1/guilds/:guildId/welcome

Get welcome/goodbye config.

PATCH /v1/guilds/:guildId/welcome

Update welcome config. Body: welcome/goodbye settings.

POST /v1/guilds/:guildId/welcome/test

Send test welcome message.

GET /v1/guilds/:guildId/autoroles

List autoroles.

POST /v1/guilds/:guildId/autoroles

Add autorole. Body: { "role_id": "123", "delay": 0 }

DELETE /v1/guilds/:guildId/autoroles/:roleId

Remove autorole.

Logging Endpoints

GET /v1/guilds/:guildId/logging

Get logging config.

PATCH /v1/guilds/:guildId/logging

Update logging config. Body: logging settings.

POST /v1/guilds/:guildId/logging/test

Send test log for all enabled events.

GET /v1/guilds/:guildId/logging/ignored

List ignored channels/roles.

POST /v1/guilds/:guildId/logging/ignored

Add ignored. Body: { "type": "channel|role", "target_id": "123" }

DELETE /v1/guilds/:guildId/logging/ignored/:type/:targetId

Remove ignored.

Roles Endpoints

GET /v1/guilds/:guildId/roles

List all roles with member counts.

POST /v1/guilds/:guildId/roles

Create role. Body: { "name": "Role", "color": "#7c5cff", "hoist": false, "mentionable": false, "permissions": "0" }

PATCH /v1/guilds/:guildId/roles/:roleId

Update role.

DELETE /v1/guilds/:guildId/roles/:roleId

Delete role.

POST /v1/guilds/:guildId/roles/bulk

Bulk add/remove. Body: { "action": "add|remove", "role_id": "123", "target": "all|bots|humans|no_roles", "user_ids": [], "reason": "Reason" }

Embed Endpoints

GET /v1/guilds/:guildId/embeds

List saved embeds.

POST /v1/guilds/:guildId/embeds

Save embed. Body: embed object + name/description.

PATCH /v1/guilds/:guildId/embeds/:embedId

Update saved embed.

DELETE /v1/guilds/:guildId/embeds/:embedId

Delete saved embed.

POST /v1/guilds/:guildId/embeds/preview

Send test embed. Body: embed object + { "channel_id": "123", "content": "optional" }

Webhooks

Lyx can send webhooks for external integrations.

GET /v1/guilds/:guildId/webhooks

List configured webhooks.

POST /v1/guilds/:guildId/webhooks

Create webhook. Body: { "url": "https://...", "events": ["moderation", "automod", "welcome"], "secret": "optional" }

DELETE /v1/guilds/:guildId/webhooks/:webhookId

Delete webhook.