Skip to main content

​
Z-Craft API Reference 🚀

Welcome to the comprehensive API documentation for Z-Craft, the premier Java Edition Lifesteal PvP Minecraft server. Our REST API provides programmatic access to player statistics, server data, lifesteal mechanics, and administrative functions.

​
API Overview

The Z-Craft API is a RESTful service that enables developers, server administrators, and third-party applications to interact with our server infrastructure. Built with security, performance, and reliability in mind.

​
Base URL

https://api.z-craft.xyz/v1

​
Key Features

Rate Limiting: 1000 requests per hour per API key Response Format: JSON (application/json) Authentication: Bearer token required HTTPS Only: All requests must use HTTPS

​
Authentication

All API requests require authentication using Bearer tokens. You can obtain an API key through our developer portal or by contacting staff.

​
Authentication Methods

Bearer Token Authentication: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.z-craft.xyz/v1/players
API Key Header: 
curl -H "X-API-Key: YOUR_API_KEY" \
     https://api.z-craft.xyz/v1/players

​
API Key Scopes

ScopeDescriptionEndpoints
read:playersRead player data and statistics/players/* (GET only)
read:serverAccess server status and metrics/server/* (GET only)
write:playersModify player data/players/* (POST/PUT/PATCH)
adminFull administrative accessAll endpoints

​
Response Format

All API responses follow a consistent JSON structure: 
{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2024-12-19T10:30:00Z",
    "request_id": "req_1234567890",
    "version": "v1"
  }
}

​
Error Responses

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request parameters are invalid",
    "details": {
      "field": "player_id",
      "issue": "must be a valid UUID"
    }
  },
  "meta": {
    "timestamp": "2024-12-19T10:30:00Z",
    "request_id": "req_1234567890"
  }
}

​
Rate Limiting

API requests are rate-limited to prevent abuse and ensure fair usage.

​
Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
X-RateLimit-Retry-After: 3600

​
Rate Limit Exceeded Response

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "reset_time": "2024-12-19T11:30:00Z"
    }
  }
}

​
SDKs & Libraries

​
Official SDKs

JavaScript SDK

Official JavaScript/TypeScript SDK for Node.js and browsers

Python SDK

Official Python SDK with async support

Java SDK

Official Java SDK for Minecraft plugins and applications

​
Community Libraries

  • C# SDK (by community)
  • Go SDK (by community)
  • PHP SDK (by community)

​
Quick Start

​
1. Get Your API Key

Visit our developer portal to register and obtain your API key.

​
2. Make Your First Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.z-craft.xyz/v1/server/status

​
3. Handle the Response

{
  "success": true,
  "data": {
    "online": true,
    "players_online": 1250,
    "max_players": 2500,
    "tps": 19.95,
    "uptime": "7 days, 14 hours"
  },
  "meta": {
    "timestamp": "2024-12-19T10:30:00Z",
    "request_id": "req_1234567890",
    "version": "v1"
  }
}

​
API Endpoints Overview

​
Player Endpoints

Player API

Access player statistics, hearts, rankings, and profile data

​
Server Endpoints

Server API

Server status, metrics, and administrative functions

​
Administrative Endpoints

Admin API

Staff-only endpoints for server management and moderation

​
Webhooks

Z-Craft supports webhooks for real-time event notifications. Configure webhook URLs in your developer dashboard.

​
Supported Events

  • player.join - Player joins the server
  • player.leave - Player leaves the server
  • player.death - Player dies (includes lifesteal data)
  • player.achievement - Player unlocks achievement
  • server.restart - Server restart notifications
  • admin.action - Administrative actions taken

​
Webhook Payload Example

{
  "event": "player.death",
  "timestamp": "2024-12-19T10:30:00Z",
  "data": {
    "player_id": "550e8400-e29b-41d4-a716-446655440000",
    "player_name": "ProGamer123",
    "hearts_lost": 1,
    "killer_id": "550e8400-e29b-41d4-a716-446655440001",
    "killer_name": "ElitePvPer",
    "location": {
      "world": "pvp-arena",
      "x": 123.5,
      "y": 64.0,
      "z": -456.8
    }
  }
}

​
Support & Community

​
Getting Help

  1. Check the Documentation - Review endpoint specifications and examples
  2. API Status Page - Check status.z-craft.xyz for outages
  3. Developer Discord - Join our developer community
  4. Contact Support - Use modmail for urgent issues

​
Changelog

Stay updated with API changes by following our API changelog. Recent Updates:
  • v1.2.0 (Dec 2024): Added bulk player data endpoints
  • v1.1.5 (Nov 2024): Enhanced rate limiting with burst allowances
  • v1.1.0 (Oct 2024): Added webhook support for real-time events
Ready to build with Z-Craft’s API? Start with our quick start guide or dive into the endpoint documentation. 🔧
API Version: v1.2.0 | Last updated: December 2024