SkyHelper OpenAPI Documentation

This is the documentation for SkyHelper API.

BaseURL

https://api.skyhelper.xyz/

Admin routes are intentionally not publicly documented as they can only be accessed by the bot's owner/admins. If you are running your own instance, ensure your Discord ID is included in the OWNER array in the config.ts file. You can view the available admin routes by inspecting packages/skyhelper/src/api/controllers/admin.controller.ts.

Getting Started

Authentication

Most endpoints require OAuth2 Bearer token authentication:

Authorization: Bearer YOUR_DISCORD_ACCESS_TOKEN

Public endpoints (health checks, embeds) don't require authentication.

Rate Limiting

The API implements rate limiting to ensure fair usage and system stability:

Limit: 60 requests per minute per IP address
Window: 60 seconds (sliding window)
Response: 429 Too Many Requests when limit is exceeded
Headers: Retry-After header indicates when to retry (in seconds)

These rate limits do not apply to the bot's own services. If you are hosting your own instance, ensure you set the x-api-key header in your requests with the value from the API_ALLOWLIST_KEY environment variable configured for your bot/API instance.

Response Format

All responses are in JSON format with appropriate HTTP status codes:

200 - Success
400 - Bad Request (invalid parameters)
401 - Unauthorized (missing/invalid token)
404 - Not Found
429 - Too Many Requests (rate limit exceeded)
500 - Internal Server Error

API Categories

🔧 Application

Core application endpoints for health checks and general bot functionality:

Health Check - Verify API status
Shard Information - Get Discord embed data for shards
Event Times - Get Sky game event scheduling information

These endpoints provide essential bot status information and pre-formatted Discord embeds for integration.

📊 Bot Statistics

Endpoints for retrieving bot performance metrics and game data:

Bot Stats - Server count, member count, performance metrics
Spirits Data - Available seasonal spirits with metadata

Perfect for dashboards, status pages, or integrating bot statistics into other applications.

🏛️ Guild Management

Comprehensive Discord server configuration and management:

Guild Settings - Get and update server preferences
Feature Management - Enable/disable bot features (live-updates, reminders)
Channel Access - List available channels with webhook permissions
Role Management - Retrieve server roles for configuration

Requires user authentication and appropriate server permissions.

👤 User Management

User-specific settings and profile management:

User Preferences - Language settings and personalization
Role Metadata - Game-specific user data (wings count, achievements)

Allows users to customize their bot experience and track game progress.

🎮 Event Management

Sky: Children of the Light game event data management:

Current Events - Active in-game events information
Daily Quests - Quest data and guides
Traveling Spirit - Weekly spirit rotation data

Admin Only: Event management endpoints require administrative privileges.

Authentication Flow

Obtain Discord OAuth2 Token
- Use Discord's OAuth2 flow to get an access token
- Scopes needed: identify for basic user info

Include in Requests

Authorization: Bearer your_access_token_here

Permission Checks
- Guild endpoints verify user has manage server permissions
- Event management requires bot administrator status

Common Use Cases

Dashboard Integration

// Get bot statistics
const stats = await fetch("https://api.skyhelper.xyz/stats");

// Get guild settings
const guild = await fetch(`https://api.skyhelper.xyz/guilds/${guildId}`, {
  headers: { Authorization: `Bearer ${token}` },
});

Discord Bot Integration

// Get pre-formatted embeds
const shardsEmbed = await fetch(
  "https://api.skyhelper.xyz/shards-embed?locale=en-US", 
);

const timesEmbed = await fetch(
  "https://api.skyhelper.xyz/times-embed?locale=en-US", 
);

User Management

// Update user language preference
await fetch(`https://api.skyhelper.xyz/users/${userId}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ language: "fr-FR" }),
});

Error Handling

The API uses standard HTTP status codes and returns detailed error messages:

{
  "statusCode": 400,
  "message": "Invalid request parameters",
  "error": "Bad Request"
}

Common error scenarios:

401 Unauthorized: Missing or invalid OAuth2 token
403 Forbidden: Insufficient permissions for the requested resource
404 Not Found: Guild or user not found
400 Bad Request: Invalid request body or parameters

Support and Feedback

Documentation Issues: Report in our GitHub repository
Discord Community: Join our Discord server for community support

Explore the endpoints in the navigation menu to get detailed information about request/response schemas, examples, and implementation details.

SkyHelper OpenAPI

On this page