REST API Documentation

Programmatically manage your Hytale projects, upload new versions, and integrate UnifiedHytale into your development workflow.

Authentication

API Tokens

All API requests require authentication using an API token. You can create and manage API tokens from your dashboard.

Authorization: Bearer YOUR_API_TOKEN

Security Best Practices

• Never commit API tokens to version control
• Store tokens securely in environment variables
• Rotate tokens regularly and revoke unused ones
• Use different tokens for different environments (dev, prod)

Base URL

https://www.unifiedhytale.com/api/v1

Rate Limits

API requests are currently unlimited, but fair use is expected. We reserve the right to rate limit excessive usage.

Endpoints

GET/projects/{projectId}/versions

Description

List all versions for a project you own.

Example Request

curl -X GET "https://www.unifiedhytale.com/api/v1/projects/abc-123/versions" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "version-id",
      "version_number": "1.0.0",
      "version_name": "Initial Release",
      "status": "approved",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "count": 1
}

POST/projects/{projectId}/versions

Description

Upload a new version of your project. Versions require admin approval before going live.

Request Body (multipart/form-data)

fileRequired. The version file (max 100MB)

version_numberRequired. Version number (e.g., "1.0.0")

version_nameOptional. Display name for the version

changelogOptional. Markdown changelog

game_versionsRequired. Comma-separated list (e.g., "1.0,1.1,1.2")

Example Request

curl -X POST "https://www.unifiedhytale.com/api/v1/projects/abc-123/versions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@./my-plugin-1.0.0.jar" \
  -F "version_number=1.0.0" \
  -F "version_name=Initial Release" \
  -F "changelog=# Version 1.0.0\n\nFirst release!" \
  -F "game_versions=1.0,1.1"

Example Response

{
  "success": true,
  "message": "Version uploaded successfully",
  "data": {
    "id": "version-id",
    "version_number": "1.0.0",
    "status": "pending",
    "file_url": "https://..."
  }
}

Moderation

All uploaded versions go through moderation and start with status "pending". An admin must approve them before they become visible to users.

GET/projects/{projectId}/versions/{versionId}

Description

Get details of a specific version.

PATCH/projects/{projectId}/versions/{versionId}

Description

Update version metadata (changelog, version_name, game_versions).

Request Body (JSON)

{
  "version_name": "Updated Release Name",
  "changelog": "# Updated changelog",
  "game_versions": ["1.0", "1.1", "1.2"]
}

DELETE/projects/{projectId}/versions/{versionId}

Description

Delete a version and its associated file.

License Verification

Verify licenses from your Hytale plugins/mods to ensure users have valid purchases.

POST/api/licenses/verify

Description

Verify a license key and get plan details. No authentication required.

Request Body (JSON)

license_keyRequired. The license key to verify

server_idOptional. Server identifier for tracking

player_countOptional. Current player count on server

Example Request

curl -X POST "https://www.unifiedhytale.com/api/licenses/verify" \
  -H "Content-Type: application/json" \
  -d '{"license_key": "XXXX-XXXX-XXXX-XXXX", "server_id": "my-server"}'

Success Response

{
  "is_valid": true,
  "license": {
    "id": "license-uuid",
    "license_key": "XXXX-XXXX-XXXX-XXXX",
    "is_active": true,
    "expires_at": null
  },
  "plan": {
    "name": "Premium",
    "allows_commercial_use": true,
    "max_servers": 5,
    "max_players": 100
  }
}

Error Response

{
  "is_valid": false,
  "failure_reason": "Invalid or inactive license"
}

Implementation Note

Call this endpoint on server startup and periodically during runtime. All verification attempts are logged for analytics.

Error Codes

400Bad Request - Invalid parameters

401Unauthorized - Invalid or missing API token

403Forbidden - You don't own this resource

404Not Found - Resource doesn't exist

500Internal Server Error - Something went wrong on our end

CI/CD Integration

Automate version uploads in your build pipeline:

GitHub Actions Example

name: Release

on:
  release:
    types: [published]

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Build
        run: ./gradlew build

      - name: Upload to UnifiedHytale
        env:
          HYTALE_API_TOKEN: ${{ secrets.HYTALE_API_TOKEN }}
          PROJECT_ID: ${{ secrets.HYTALE_PROJECT_ID }}
        run: |
          curl -X POST "https://www.unifiedhytale.com/api/v1/projects/$PROJECT_ID/versions" \
            -H "Authorization: Bearer $HYTALE_API_TOKEN" \
            -F "file=@./build/libs/my-plugin.jar" \
            -F "version_number=${{ github.event.release.tag_name }}" \
            -F "version_name=${{ github.event.release.name }}" \
            -F "changelog=${{ github.event.release.body }}" \
            -F "game_versions=1.0,1.1,1.2"

Support

Need help? Join our Discord community or contact support.

Authentication

API Tokens

All API requests require authentication using an API token. You can create and manage API tokens from your dashboard.

Authorization: Bearer YOUR_API_TOKEN

Security Best Practices

• Never commit API tokens to version control
• Store tokens securely in environment variables
• Rotate tokens regularly and revoke unused ones
• Use different tokens for different environments (dev, prod)

Endpoints

GET/projects/{projectId}/versions

Description

List all versions for a project you own.

Example Request

curl -X GET "https://www.unifiedhytale.com/api/v1/projects/abc-123/versions" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "version-id",
      "version_number": "1.0.0",
      "version_name": "Initial Release",
      "status": "approved",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "count": 1
}

POST/projects/{projectId}/versions

Description

Upload a new version of your project. Versions require admin approval before going live.

Request Body (multipart/form-data)

fileRequired. The version file (max 100MB)

version_numberRequired. Version number (e.g., "1.0.0")

version_nameOptional. Display name for the version

changelogOptional. Markdown changelog

game_versionsRequired. Comma-separated list (e.g., "1.0,1.1,1.2")

Example Request

curl -X POST "https://www.unifiedhytale.com/api/v1/projects/abc-123/versions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@./my-plugin-1.0.0.jar" \
  -F "version_number=1.0.0" \
  -F "version_name=Initial Release" \
  -F "changelog=# Version 1.0.0\n\nFirst release!" \
  -F "game_versions=1.0,1.1"

Example Response

{
  "success": true,
  "message": "Version uploaded successfully",
  "data": {
    "id": "version-id",
    "version_number": "1.0.0",
    "status": "pending",
    "file_url": "https://..."
  }
}

Moderation

All uploaded versions go through moderation and start with status "pending". An admin must approve them before they become visible to users.

GET/projects/{projectId}/versions/{versionId}

Description

Get details of a specific version.

PATCH/projects/{projectId}/versions/{versionId}

Description

Update version metadata (changelog, version_name, game_versions).

Request Body (JSON)

{
  "version_name": "Updated Release Name",
  "changelog": "# Updated changelog",
  "game_versions": ["1.0", "1.1", "1.2"]
}

DELETE/projects/{projectId}/versions/{versionId}

Description

Delete a version and its associated file.

License Verification

Verify licenses from your Hytale plugins/mods to ensure users have valid purchases.

POST/api/licenses/verify

Description

Verify a license key and get plan details. No authentication required.

Request Body (JSON)

license_keyRequired. The license key to verify

server_idOptional. Server identifier for tracking

player_countOptional. Current player count on server

Example Request

curl -X POST "https://www.unifiedhytale.com/api/licenses/verify" \
  -H "Content-Type: application/json" \
  -d '{"license_key": "XXXX-XXXX-XXXX-XXXX", "server_id": "my-server"}'

Success Response

{
  "is_valid": true,
  "license": {
    "id": "license-uuid",
    "license_key": "XXXX-XXXX-XXXX-XXXX",
    "is_active": true,
    "expires_at": null
  },
  "plan": {
    "name": "Premium",
    "allows_commercial_use": true,
    "max_servers": 5,
    "max_players": 100
  }
}

Error Response

{
  "is_valid": false,
  "failure_reason": "Invalid or inactive license"
}

Implementation Note

Call this endpoint on server startup and periodically during runtime. All verification attempts are logged for analytics.

CI/CD Integration

Automate version uploads in your build pipeline:

GitHub Actions Example

name: Release

on:
  release:
    types: [published]

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Build
        run: ./gradlew build

      - name: Upload to UnifiedHytale
        env:
          HYTALE_API_TOKEN: ${{ secrets.HYTALE_API_TOKEN }}
          PROJECT_ID: ${{ secrets.HYTALE_PROJECT_ID }}
        run: |
          curl -X POST "https://www.unifiedhytale.com/api/v1/projects/$PROJECT_ID/versions" \
            -H "Authorization: Bearer $HYTALE_API_TOKEN" \
            -F "file=@./build/libs/my-plugin.jar" \
            -F "version_number=${{ github.event.release.tag_name }}" \
            -F "version_name=${{ github.event.release.name }}" \
            -F "changelog=${{ github.event.release.body }}" \
            -F "game_versions=1.0,1.1,1.2"