> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.z-craft.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# API Reference
> Complete developer documentation for Z-Craft's REST API, including player data, server statistics, lifesteal mechanics, and administrative endpoints
# 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](https://developers.z-craft.xyz) or by contacting staff.
### Authentication Methods
**Bearer Token Authentication:**
```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.z-craft.xyz/v1/players
```
**API Key Header:**
```bash theme={null}
curl -H "X-API-Key: YOUR_API_KEY" \
https://api.z-craft.xyz/v1/players
```
### API Key Scopes
| Scope | Description | Endpoints |
| --------------- | -------------------------------- | ----------------------------- |
| `read:players` | Read player data and statistics | `/players/*` (GET only) |
| `read:server` | Access server status and metrics | `/server/*` (GET only) |
| `write:players` | Modify player data | `/players/*` (POST/PUT/PATCH) |
| `admin` | Full administrative access | All endpoints |
## Response Format
All API responses follow a consistent JSON structure:
```json theme={null}
{
"success": true,
"data": {
// Response data
},
"meta": {
"timestamp": "2024-12-19T10:30:00Z",
"request_id": "req_1234567890",
"version": "v1"
}
}
```
### Error Responses
```json theme={null}
{
"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
```http theme={null}
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
X-RateLimit-Retry-After: 3600
```
### Rate Limit Exceeded Response
```json theme={null}
{
"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
Official JavaScript/TypeScript SDK for Node.js and browsers
Official Python SDK with async support
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](https://developers.z-craft.xyz) to register and obtain your API key.
### 2. Make Your First Request
```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.z-craft.xyz/v1/server/status
```
### 3. Handle the Response
```json theme={null}
{
"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
Access player statistics, hearts, rankings, and profile data
### Server Endpoints
Server status, metrics, and administrative functions
### Administrative Endpoints
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](https://developers.z-craft.xyz/webhooks).
### 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
```json theme={null}
{
"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](https://status.z-craft.xyz) for outages
3. **Developer Discord** - Join our [developer community](https://discord.gg/z-craft-dev)
4. **Contact Support** - Use [modmail](/support/modmail) for urgent issues
### Changelog
Stay updated with API changes by following our [API changelog](https://developers.z-craft.xyz/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](/getting-started/account-setup) or dive into the [endpoint documentation](/api-reference/endpoint/get). 🔧
***
*API Version: v1.2.0 | Last updated: December 2024*