Teleport API 🔒

Player teleportation endpoints. All endpoints require admin privileges.

Teleport Player

Teleport a player to another player or location.

Endpoint: POST /api/teleport

Authentication: Required (JWT, Admin)

Request Body:

{
  "player": "Player123",
  "target": "Player456"
}

Success Response (200):

{
  "success": true,
  "message": "Player123 teleported to Player456",
  "location": {
    "world": "world",
    "x": 100.5,
    "y": 64.0,
    "z": -250.3
  }
}

Example:

curl -X POST http://localhost:8080/api/teleport \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "player": "Player123",
    "target": "Player456"
  }'

Error Responses:

• 400 - Missing player or target
• 403 - Admin privileges required
• 404 - Player or target not found

---

Teleport to Coordinates

Teleport a player to specific coordinates.

Endpoint: POST /api/admin/teleport-coordinates

Authentication: Required (JWT, Admin)

Request Body:

{
  "player": "Player123",
  "world": "world",
  "x": 100.5,
  "y": 64.0,
  "z": -250.3,
  "yaw": 0.0,
  "pitch": 0.0
}

Parameters:

• player - Player username (required)
• world - World name (required)
• x - X coordinate (required)
• y - Y coordinate (required)
• z - Z coordinate (required)
• yaw - View direction horizontal (optional, default: 0.0)
• pitch - View direction vertical (optional, default: 0.0)

Success Response (200):

{
  "success": true,
  "message": "Player123 teleported to coordinates",
  "location": {
    "world": "world",
    "x": 100.5,
    "y": 64.0,
    "z": -250.3,
    "yaw": 0.0,
    "pitch": 0.0
  }
}

Example:

curl -X POST http://localhost:8080/api/admin/teleport-coordinates \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "player": "Player123",
    "world": "world",
    "x": 100.5,
    "y": 64.0,
    "z": -250.3
  }'

Error Responses:

• 400 - Invalid coordinates or missing parameters
• 403 - Admin privileges required
• 404 - Player or world not found

---

Teleport to Player

Teleport yourself or another player to a target player.

Endpoint: POST /api/admin/teleport-player

Authentication: Required (JWT, Admin)

Request Body:

{
  "player": "Player123",
  "targetPlayer": "Player456"
}

Success Response (200):

{
  "success": true,
  "message": "Player123 teleported to Player456",
  "location": {
    "world": "world",
    "x": 100.5,
    "y": 64.0,
    "z": -250.3
  }
}

Example:

curl -X POST http://localhost:8080/api/admin/teleport-player \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "player": "Player123",
    "targetPlayer": "Player456"
  }'

---

Code Examples

TypeScript

interface TeleportLocation {
  world: string;
  x: number;
  y: number;
  z: number;
  yaw?: number;
  pitch?: number;
}

class TeleportAPI {
  constructor(private baseUrl: string, private adminToken: string) {}
  
  async teleportToPlayer(player: string, target: string) {
    const response = await fetch(`${this.baseUrl}/api/teleport`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.adminToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ player, target })
    });
    return await response.json();
  }
  
  async teleportToCoordinates(
    player: string,
    location: TeleportLocation
  ) {
    const response = await fetch(
      `${this.baseUrl}/api/admin/teleport-coordinates`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.adminToken}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ player, ...location })
      }
    );
    return await response.json();
  }
  
  async teleportPlayerToPlayer(player: string, targetPlayer: string) {
    const response = await fetch(
      `${this.baseUrl}/api/admin/teleport-player`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.adminToken}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ player, targetPlayer })
      }
    );
    return await response.json();
  }
  
  // Convenience method: teleport to spawn
  async teleportToSpawn(player: string) {
    return this.teleportToCoordinates(player, {
      world: 'world',
      x: 0,
      y: 64,
      z: 0
    });
  }
}

Python

class TeleportAPI:
    def __init__(self, base_url, admin_token):
        self.base_url = base_url
        self.headers = {
            'Authorization': f'Bearer {admin_token}',
            'Content-Type': 'application/json'
        }
    
    def teleport_to_player(self, player, target):
        response = requests.post(
            f'{self.base_url}/api/teleport',
            headers=self.headers,
            json={'player': player, 'target': target}
        )
        return response.json()
    
    def teleport_to_coordinates(self, player, world, x, y, z, yaw=0.0, pitch=0.0):
        response = requests.post(
            f'{self.base_url}/api/admin/teleport-coordinates',
            headers=self.headers,
            json={
                'player': player,
                'world': world,
                'x': x,
                'y': y,
                'z': z,
                'yaw': yaw,
                'pitch': pitch
            }
        )
        return response.json()
    
    def teleport_player_to_player(self, player, target_player):
        response = requests.post(
            f'{self.base_url}/api/admin/teleport-player',
            headers=self.headers,
            json={'player': player, 'targetPlayer': target_player}
        )
        return response.json()
    
    def teleport_to_spawn(self, player):
        """Convenience method to teleport to spawn"""
        return self.teleport_to_coordinates(player, 'world', 0, 64, 0)

Java

public class TeleportAPI {
    private final String baseUrl;
    private final String adminToken;
    private final HttpClient client;
    
    public TeleportAPI(String baseUrl, String adminToken) {
        this.baseUrl = baseUrl;
        this.adminToken = adminToken;
        this.client = HttpClient.newHttpClient();
    }
    
    public void teleportToCoordinates(
        String player,
        String world,
        double x,
        double y,
        double z
    ) throws Exception {
        String json = String.format(
            "{\"player\":\"%s\",\"world\":\"%s\",\"x\":%.2f,\"y\":%.2f,\"z\":%.2f}",
            player, world, x, y, z
        );
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/api/admin/teleport-coordinates"))
            .header("Authorization", "Bearer " + adminToken)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();
        
        client.send(request, HttpResponse.BodyHandlers.ofString());
    }
}

Use Cases

Event Teleportation

// Teleport all players to event location
async function startEvent(api: TeleportAPI, players: string[]) {
  const eventLocation = {
    world: 'world',
    x: 500,
    y: 100,
    z: -500
  };
  
  for (const player of players) {
    await api.teleportToCoordinates(player, eventLocation);
  }
}

Spawn Return

// Return player to spawn on death or request
async function returnToSpawn(api: TeleportAPI, player: string) {
  await api.teleportToCoordinates(player, {
    world: 'world',
    x: 0,
    y: 64,
    z: 0
  });
}

Admin Support

// Teleport to player for support
async function supportPlayer(api: TeleportAPI, admin: string, player: string) {
  await api.teleportPlayerToPlayer(admin, player);
}

World Names

Common world names:

• world - Overworld
• world_nether - Nether
• world_the_end - The End

Custom worlds use their configured name from bukkit.yml.

Coordinate Ranges

Valid coordinate ranges:

• X/Z: -29,999,984 to 29,999,984
• Y: Varies by version
  • 1.18+: -64 to 319
  • Pre-1.18: 0 to 255

Safety Considerations

• Verify destination is safe before teleporting
• Check for solid ground at Y coordinate
• Avoid teleporting into blocks
• Consider fall damage when teleporting to high Y
• Players may be teleported across dimensions

Notes

• All teleport endpoints require admin authentication
• Players must be online to be teleported
• Teleportation is instant (no delay)
• No warm-up or cooldown periods
• Bypass all teleport restrictions
• Target players notified of teleportation
• Logs maintained for all teleports

Related

• Admin API - Other admin operations
• Players API - Player information
• Server API - World information