API Reference

The Custom Skin API handles skin signature generation and real-time sync. This reference is for developers who want to integrate with or self-host the API.

Base URL


https://ccapi.thomas.md

Authentication

Plugin Authentication

Plugins use an API key in the X-API-Key header:


X-API-Key: your-plugin-api-key

Dashboard Authentication

The dashboard uses Bearer tokens generated via the /tokens/generate endpoint:


Authorization: Bearer <token>

Endpoints

Health Check


GET /health

Returns 200 OK if the API is running.

Generate Dashboard Token


POST /tokens/generate
Content-Type: application/json
X-API-Key: <plugin-api-key>
 
{
  "minecraft_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "minecraft_username": "Steve",
  "server_id": "my-server"
}

Response:


{
  "success": true,
  "token": "abc123...",
  "dashboard_url": "https://skin.thomas.md/dashboard?token=abc123...",
  "expires_in_hours": 24
}

Get Skin Configuration


GET /skins/:minecraft_uuid

Response:


{
  "success": true,
  "skin": {
    "id": "uuid",
    "minecraft_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "minecraft_username": "Steve",
    "cape_type": "vanilla",
    "loop_mode": "loop",
    "frame_duration_ticks": 10,
    "enabled": true,
    "frames": [
      {
        "frame_index": 0,
        "texture_value": "eyJ0aW1lc3RhbXAi...",
        "texture_signature": "kZQmMGv3fJ...",
        "texture_url": "https://textures.minecraft.net/..."
      }
    ]
  }
}

Upload Skin


POST /skins/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data
 
skin: <PNG file>
cape_type: vanilla
variant: classic

Response: Same as Get Skin Configuration

Update Configuration


PUT /skins/:minecraft_uuid/config
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "loop_mode": "ping-pong",
  "frame_duration_ticks": 15,
  "enabled": true
}

Delete Skin


DELETE /skins/:minecraft_uuid
Authorization: Bearer <token>

WebSocket API

Connection


wss://ccapi.thomas.md/ws/plugin?api_key=<plugin-api-key>

Messages

Player Online:


{
  "type": "player_online",
  "minecraft_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "minecraft_username": "Steve"
}

Skin Updated (from server):


{
  "type": "skin_updated",
  "minecraft_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "minecraft_username": "Steve"
}

Config Changed (from server):


{
  "type": "config_changed",
  "minecraft_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "loop_mode": "loop",
  "frame_duration_ticks": 10,
  "enabled": true
}

Error Responses


{
  "success": false,
  "error": "Error description"
}

Status Code	Description
400	Bad request (invalid input)
401	Unauthorized (invalid/missing token)
404	Resource not found
500	Internal server error