API Documentation

Programmatic access to ServerJars Minecraft builds

API Version v1

Getting Started

Base URL

https://serverjars.sir.systems/api/v1/

Authentication

No authentication required. Please use responsibly.

Response Format

{
  "success": true,   // Request status
  "status": 200,     // HTTP status code
  "message": "",     // Optional message
  // Endpoint-specific data
}

Rate Limits

60 requests per minute per IP address

GET

/builds

200

Retrieve Minecraft server builds with optional filters.

Parameters

game_version
Minecraft version
software_version
Software version
build_number
Build number
fork
Server fork

Example Request

GET /api/v1/builds?fork=Paper&game_version=1.20.1
GET

/stats

200

Retrieve statistics about the ServerJars service.

Response Structure

{
  "storage": {
    "bucket_size": "15.7 GB",
    "object_count": 2450
  },
  "builds": {
    "total": 2450,
    "forks": [
      {"fork": "Paper", "count": 850},
      {"fork": "Purpur", "count": 420}
    ]
  }
}
GET

/search

200

Search for a specific build by ID.

Parameters

id
Build ID (required)

Example Response

{
  "id": 123,
  "game_version": "1.20.1",
  "fork": "Paper",
  "build_number": 456,
  "download_link": "https://..."
}

Error Handling

400

Bad Request

Invalid parameters or missing required fields

404

Not Found

Requested resource could not be found

500

Server Error

Internal server error occurred

Code Examples

JavaScript

// Get Paper builds for 1.20.1
fetch('https://serverjars.sir.systems/api/v1/builds?fork=Paper&game_version=1.20.1')
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log('Builds:', data.builds);
    } else {
      console.error('Error:', data.message);
    }
  });

Python

import requests

# Get service statistics
response = requests.get('https://serverjars.sir.systems/api/v1/stats')
data = response.json()

if data['success']:
    print(f"Total builds: {data['stats']['builds']['total']}")
    for fork in data['stats']['builds']['forks']:
        print(f"{fork['fork']}: {fork['count']} builds")
else:
    print("Error:", data['message'])

Best Practices

  • Always check the success field before processing data
  • Handle errors using the message field
  • Cache responses when possible to reduce server load
  • Include a descriptive User-Agent header with your requests
  • Respect the rate limit of 60 requests per minute