Downloads API - Download Endpoints

Downloads API - Download Endpoints

Download plugin JAR files directly from the API. All download endpoints return the actual plugin file ready to use.

Overview

Download endpoints provide direct access to plugin JAR files. They return binary data with appropriate headers for file downloads.

Download Latest Version (by Server Software)

Download the latest plugin version for a specific server software (any Java version).

Endpoint: GET /api/plugin-versions/download/latest/:serverSoftware

Authentication: Not required (public endpoint)

URL Parameters

• serverSoftware (required) - Server software name (case-insensitive)
  • Normal servers: PaperMC, Spigot, Bukkit, Purpur, Quilt, LeafMC
  • Folia servers: Folia, CanvasMC
  • Proxy servers: BungeeCord, Waterfall, Velocity

Example Request

curl

curl -O -J "https://api.statsly.org/api/plugin-versions/download/latest/PaperMC"

Response

Returns a JAR file with the following headers:

• Content-Type: application/java-archive
• Content-Disposition: attachment; filename="Statsly-1.0.jar"
• Content-Length: <file-size>

Tip

Use the -O -J flags with curl to save the file with the correct filename. The -J flag respects the Content-Disposition header.

Example: PowerShell

download.ps1

$url = "https://api.statsly.org/api/plugin-versions/download/latest/PaperMC"
$output = "plugins\Statsly.jar"

Invoke-WebRequest -Uri $url -OutFile $output

Download Latest Version (by Server Software + Java Version)

Download the latest plugin version for a specific server software and Java version combination.

Endpoint: GET /api/plugin-versions/download/latest/:serverSoftware/:javaVersion

Authentication: Not required (public endpoint)

URL Parameters

• serverSoftware (required) - Server software name
• javaVersion (required) - Java version (8, 11, 17, or 21)

Example Request

curl

curl -O -J "https://api.statsly.org/api/plugin-versions/download/latest/PaperMC/17"

Response

Returns a JAR file download (same format as above).

Tip

Specifying a Java version ensures you get a version compatible with your server’s Java installation. This is recommended for production servers.

Download Specific Version

Download a specific plugin version by its unique ID.

Endpoint: GET /api/plugin-versions/download/:id

Authentication: Not required (public endpoint)

URL Parameters

• id (required) - Plugin version ID (e.g., plugin-1234567890-abc123)

Example Request

curl

curl -O -J "https://api.statsly.org/api/plugin-versions/download/plugin-1234567890-abc123"

Response

Returns a JAR file download (same format as above).

Tip

Use specific version IDs for reproducible builds and to ensure you’re always using the same plugin version across multiple servers.

Server-Specific Endpoints

For convenience, each server software has dedicated endpoints using lowercase names:

Normal Servers

• GET /api/plugin-versions/download/latest/papermc
• GET /api/plugin-versions/download/latest/spigot
• GET /api/plugin-versions/download/latest/bukkit
• GET /api/plugin-versions/download/latest/purpur
• GET /api/plugin-versions/download/latest/quilt
• GET /api/plugin-versions/download/latest/leafmc

Folia Servers

• GET /api/plugin-versions/download/latest/folia
• GET /api/plugin-versions/download/latest/canvasmc

Proxy Servers

• GET /api/plugin-versions/download/latest/bungeecord
• GET /api/plugin-versions/download/latest/waterfall
• GET /api/plugin-versions/download/latest/velocity

Note

Server software names are case-insensitive. Both PaperMC and papermc will work. The lowercase endpoints are provided for convenience and consistency.

Error Handling

HTTP Status Codes

• 200 - Success (JAR file returned)
• 404 - Not Found (no version available for the specified criteria)
• 429 - Too Many Requests (rate limit exceeded)
• 500 - Internal Server Error

Error Response Format

error.json

{
  "error": "No plugin version found for PaperMC"
}

Example Error Handling

error-handling.js

async function downloadPlugin(serverSoftware, javaVersion) {
  try {
    const url = `https://api.statsly.org/api/plugin-versions/download/latest/${serverSoftware}/${javaVersion}`;
    const response = await fetch(url);

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error('No plugin version found for your server software');
      }
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    const blob = await response.blob();
    const filename = response.headers.get('Content-Disposition')?.split('filename=')[1]?.replace(/[""]/g, '') || 'Statsly.jar';

    // Save file
    return { success: true, filename, blob };
  } catch (error) {
    console.error('Download failed:', error);
    return { success: false, error: error.message };
  }
}

Best Practices

Download Optimization

• Use specific version IDs for reproducible builds
• Use latest endpoints for automatic updates
• Specify Java version for better compatibility
• Cache downloaded files locally

Automation

• Implement retry logic with exponential backoff
• Check file integrity after download
• Verify file size matches expected size
• Handle network interruptions gracefully

Tip

For production servers, consider downloading specific versions by ID rather than always using “latest” to ensure stability and reproducibility.

Next Steps

• Learn about Metadata Endpoints
• Check out Usage Examples
• Review Error Handling & Best Practices