Crafty Controller API Skill

⚙️ CONFIGURATION — SET THESE BEFORE ANYTHING ELSE

CODEBLOCK0

Where to find your API key:
Log into Crafty Controller → click your username (top right) → API Key tab → copy the token.

Overview

Crafty Controller exposes a REST API under /api/v2. All endpoints require Bearer token authentication. The API covers:

Python Helper Setup

Install dependencies first:

CODEBLOCK1

Base client to reuse everywhere:

CODEBLOCK2

1. Servers

List All Servers

Get Single Server Details

Create a New Server

Update Server Settings

Delete a Server

def delete_server(server_id: str):
    """Permanently delete a server from Crafty (does NOT delete files by default)."""
    return crafty_delete(f"/servers/{server_id}")

2. Server Power Actions

All power actions POST to /servers/{server_id}/action/{action}.

CODEBLOCK8

3. Console & Commands

Send a Console Command

Common Command Shortcuts

Get Server Logs

def get_logs(server_id: str):
    """Retrieve recent console log output for a server."""
    return crafty_get(f"/servers/{server_id}/logs")

4. Server Stats

CODEBLOCK12

Get Stats for All Servers

def get_all_stats():
    """Snapshot stats for every registered server."""
    return crafty_get("/servers/stats")

5. Backups

List Backups for a Server

Trigger a Manual Backup

Get Backup Config

Update Backup Config

Delete a Backup

def delete_backup(server_id: str, backup_filename: str):
    return crafty_delete(f"/servers/{server_id}/backups/{backup_filename}")

6. Schedules

List Schedules

Create a Schedule

Update a Schedule

Delete a Schedule

def delete_schedule(server_id: str, schedule_id: str):
    return crafty_delete(f"/servers/{server_id}/schedules/{schedule_id}")

7. File Management

List Files / Browse Directory

Read a File

Write / Update a File

Create a Directory

Delete a File or Directory

Upload a File

def upload_file(server_id: str, local_file_path: str, upload_dir: str = ""):
    """Upload a local file into the server's directory."""
    url = f"{CRAFTY_BASE_URL}/servers/{server_id}/files/upload"
    with open(local_file_path, "rb") as f:
        files = {"file": f}
        data = {"path": upload_dir}
        # Note: don't pass Content-Type header for multipart
        auth_headers = {"Authorization": f"Bearer {CRAFTY_API_KEY}"}
        resp = requests.post(url, headers=auth_headers, files=files, data=data, verify=False)
    resp.raise_for_status()
    return resp.json()

8. Users

List All Users

Get a User

Create a User

Update a User

Delete a User

Update User Server Permissions

def set_user_server_permissions(user_id: str, server_id: str, permissions: list):
    """
    Permissions list can contain any of:
      "Commands", "Terminal", "Logs", "Schedule", "Backup",
      "Files", "Config", "Players"
    """
    return crafty_patch(f"/users/{user_id}", {
        "server_permissions": {server_id: permissions}
    })

9. Roles

List Roles

Get Role Details

Create a Role

Update a Role

Delete a Role

Assign Role to User

def assign_role_to_user(user_id: str, role_id: str):
    return crafty_patch(f"/users/{user_id}", {"roles": [role_id]})

10. Crafty System Info

Get Crafty Version & System Stats

Get All Audit Log Entries

def get_audit_log():
    return crafty_get("/crafty/audit-log")

Error Handling

All functions can raise requests.HTTPError. Wrap calls for production use:

CODEBLOCK43

Common Patterns

Full Server Status Dashboard

Restart All Running Servers

Edit server.properties Value

def set_property(server_id: str, key: str, value: str):
    """
    Read server.properties, change one key, write it back.
    Example: set_property(sid, "max-players", "50")
    """
    result = read_file(server_id, "server.properties")
    content = result.get("data", {}).get("content", "")
    lines = content.splitlines()
    new_lines = []
    found = False
    for line in lines:
        if line.startswith(f"{key}="):
            new_lines.append(f"{key}={value}")
            found = True
        else:
            new_lines.append(line)
    if not found:
        new_lines.append(f"{key}={value}")
    write_file(server_id, "server.properties", "\n".join(new_lines))
    print(f"✅ Set {key}={value}")

API Response Structure

Every Crafty API response follows this envelope:

CODEBLOCK47

Always check response["status"] == "ok" before using response["data"].

Notes

• - SSL: Crafty uses a self-signed certificate by default. The helpers above pass verify=False. In production, provide your real cert path: verify="/path/to/cert.pem".
• API version: This skill targets Crafty Controller v4 (/api/v2 routes). Crafty 3 uses a different API.
• Permissions: Your API key inherits the permissions of the user it belongs to. For full access, generate the key from a superuser account.
• Rate limiting: Crafty does not enforce rate limiting by default, but avoid hammering the stats endpoint — poll at most once per 5 seconds.