Skip to content
Documentation

Overview

API Reference

Section titled “API Reference”

The Orbis API provides programmatic access to servers, marketplace resources, teams, users, and more.

Authentication

Section titled “Authentication”

All API requests require authentication using an API key:

Terminal window
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.orbis.place/resources

Getting an API Key

Section titled “Getting an API Key”
  1. Log in to your Orbis account
  2. Navigate to Settings → Developer
  3. Click “Create API Key”
  4. Copy and securely store your key

Base URL

Section titled “Base URL”
https://api.orbis.place

Rate Limiting

Section titled “Rate Limiting”
  • Default: 100 requests per hour per API key
  • Rate limit headers are included in all responses

Response Format

Section titled “Response Format”

All responses are in JSON format:

{
  "data": [...],
  "meta": {
    "total": 100,
    "limit": 20,
    "offset": 0
  }
}

Error Handling

Section titled “Error Handling”

Errors return appropriate HTTP status codes:

  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid or missing API key)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found
  • 429 - Rate Limit Exceeded
  • 500 - Internal Server Error

Error responses include details:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid resource ID format",
    "details": {}
  }
}

API Sections

Section titled “API Sections”

Resources

Section titled “Resources”

Manage marketplace resources including mods, plugins, tools, and scripts.

Servers

Section titled “Servers”

Manage Hytale game server listings.

Teams

Section titled “Teams”

Manage teams and team-owned content.

  • Teams API - Team management, members, and invitations

Users

Section titled “Users”

Manage user profiles and social features.

  • Users API - User profiles, follows, and social links

Community & Moderation

Section titled “Community & Moderation”

Game Data

Section titled “Game Data”

Common Patterns

Section titled “Common Patterns”

Pagination

Section titled “Pagination”

Many endpoints support pagination using limit and offset:

GET /resources?limit=20&offset=40

Alternative page-based pagination:

GET /resources?page=3&limit=20

Filtering

Section titled “Filtering”

Filter results using query parameters:

GET /resources?type=MOD&tags=magic,combat

Array parameters can be passed multiple times or comma-separated.

Sorting

Section titled “Sorting”

Sort results using the sort parameter:

GET /resources?sort=newest
GET /servers?sort=rank

Common sort options:

  • newest - Most recently created
  • popular - Most popular/liked
  • downloads - Most downloaded (resources)
  • rank - Server rank (servers)

File Uploads

Section titled “File Uploads”

File upload endpoints use multipart/form-data:

Terminal window
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "icon=@/path/to/image.png" \
  https://api.orbis.place/resources/RESOURCE_ID/icon

Slugs vs IDs

Section titled “Slugs vs IDs”

Most resources can be accessed by either ID or slug:

  • /resources/:id - Access by ID (guaranteed unique)
  • /resources/slug/:slug - Access by slug (user-friendly URLs)

Best Practices

Section titled “Best Practices”

Security

Section titled “Security”
  • Never expose your API key in client-side code
  • Rotate API keys regularly
  • Use environment variables to store API keys
  • Implement proper error handling for 401/403 responses

Performance

Section titled “Performance”
  • Use pagination to limit response sizes
  • Cache responses when appropriate
  • Use conditional requests with ETags (when available)
  • Filter results to fetch only what you need

Error Handling

Section titled “Error Handling”
try {
  const response = await fetch('https://api.orbis.place/resources', {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });


  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', error.error.message);
    return;
  }


  const data = await response.json();
  // Process data
} catch (error) {
  console.error('Network Error:', error);
}

Support

Section titled “Support”

For API support, please:

  • Open an issue on GitHub
  • Join our Discord
  • Check the documentation for updates