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"

Query Parameters

channelOptional. Filter by release channel: "release", "beta", or "alpha"

Example Response

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

POST/projects/{projectId}/versions

Description

Upload a new version with one or more files. Versions require admin approval before going live.

Request Body (multipart/form-data)

fileRequired. Primary version file (max 500MB)

additional_filesOptional. Additional files (can include multiple)

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

version_nameOptional. Display name for the version

changelogOptional. Markdown changelog

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

release_channelOptional. One of: "release" (default), "beta", or "alpha"

Example Request (Single File)

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" \
  -F "release_channel=release"

Example Request (Multiple Files)

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 "additional_files=@./documentation.pdf" \
  -F "additional_files=@./source-code.zip" \
  -F "version_number=1.0.0" \
  -F "changelog=Includes docs and source code"

Example Response

{
  "success": true,
  "message": "Version uploaded successfully",
  "data": {
    "id": "version-id",
    "version_number": "1.0.0",
    "release_channel": "release",
    "status": "pending",
    "file_url": "https://...",
    "assets": [
      {
        "id": "asset-1",
        "file_name": "my-plugin-1.0.0.jar",
        "asset_type": "primary"
      },
      {
        "id": "asset-2",
        "file_name": "documentation.pdf",
        "asset_type": "additional"
      }
    ]
  }
}

Multiple Files

Each version can have multiple files. The first file is marked as "primary" and shown as the main download. Additional files (documentation, source code, etc.) are available as separate downloads.

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. All fields are optional.

Request Body (JSON)

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

Release Channels

• release - Stable releases for production use
• beta - Pre-release versions for testing
• alpha - Early development builds

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.

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"

Query Parameters

channelOptional. Filter by release channel: "release", "beta", or "alpha"

Example Response

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

POST/projects/{projectId}/versions

Description

Upload a new version with one or more files. Versions require admin approval before going live.

Request Body (multipart/form-data)

fileRequired. Primary version file (max 500MB)

additional_filesOptional. Additional files (can include multiple)

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

version_nameOptional. Display name for the version

changelogOptional. Markdown changelog

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

release_channelOptional. One of: "release" (default), "beta", or "alpha"

Example Request (Single File)

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" \
  -F "release_channel=release"

Example Request (Multiple Files)

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 "additional_files=@./documentation.pdf" \
  -F "additional_files=@./source-code.zip" \
  -F "version_number=1.0.0" \
  -F "changelog=Includes docs and source code"

Example Response

{
  "success": true,
  "message": "Version uploaded successfully",
  "data": {
    "id": "version-id",
    "version_number": "1.0.0",
    "release_channel": "release",
    "status": "pending",
    "file_url": "https://...",
    "assets": [
      {
        "id": "asset-1",
        "file_name": "my-plugin-1.0.0.jar",
        "asset_type": "primary"
      },
      {
        "id": "asset-2",
        "file_name": "documentation.pdf",
        "asset_type": "additional"
      }
    ]
  }
}

Multiple Files

Each version can have multiple files. The first file is marked as "primary" and shown as the main download. Additional files (documentation, source code, etc.) are available as separate downloads.

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. All fields are optional.

Request Body (JSON)

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

Release Channels

• release - Stable releases for production use
• beta - Pre-release versions for testing
• alpha - Early development builds

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.