TeamSpeak 6 REST API Guide

TeamSpeak 6 REST API & Web Query Guide

TeamSpeak 6 introduces a modernized RESTful API (often called Web Query) that replaces the traditional telnet-based ServerQuery for modern applications. This guide covers how to leverage these new tools for automation and integration.

Architecture Overview

The TS6 API operates as a web server hosted directly by the TeamSpeak server instance. It allows you to perform any administrative action that the client can do, but through standardized JSON requests.

Key Differences from TS3:

• Protocol: HTTP/HTTPS instead of Telnet
• Format: JSON instead of raw text strings with escapes
• Authentication: Granular API Keys instead of global Query Logins
• Port: Default port 10080 (HTTP) or 10443 (HTTPS)

Authentication: Creating API Keys

In TeamSpeak 6, you no longer need "ServerAdmin" query passwords for most tasks. Instead, you create API Keys with specific permissions.

How to create a key:

1. Open your TeamSpeak 6 Client.
2. Connect to your server with administrative privileges.
3. Go to Server Settings > API Keys.
4. Click Generate Key.
5. Select the scope (e.g., "Full Admin", "Moderation Only", "Viewer").
6. Copy the key and store it securely.

Making Your First Request

The base URL for the API is typically http://your-server-ip:10080/v1/.

Listing Online Clients

curl -H "x-api-key: YOUR_API_KEY" \
     "http://your-server:10080/v1/clients"

JSON Response Example:

{
  "status": "success",
  "data": [
    {
      "clid": 1,
      "nickname": "AdminUser",
      "cid": 1,
      "client_unique_identifier": "xyz...",
      "talking": false
    }
  ]
}

Common Integration Examples

1. Python: Getting Server Info

import requests

API_KEY = "your_secret_key"
BASE_URL = "http://your-server:10080/v1"

def get_server_status():
    headers = {"x-api-key": API_KEY}
    response = requests.get(f"{BASE_URL}/serverinfo", headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        print(f"Server Name: {data['data']['name']}")
        print(f"Users Online: {data['data']['clients_online']}")
    else:
        print("Failed to connect to API")

get_server_status()

2. Moderation: Kicking a User

To kick a user, you send a POST request to the /clients/kick endpoint.

# Data payload
{
  "clid": 12,
  "reason": "Inappropriate behavior",
  "kick_type": "server"
}

# Curl command
curl -X POST -H "x-api-key: YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"clid": 12, "reason": "Spam"}' \
     "http://your-server:10080/v1/clients/kick"

Advanced: Webhooks Support

TeamSpeak 6 supports Outbound Webhooks, allowing the server to push events to your application in real-time without polling.

Supported Events:

• client_connect / client_disconnect
• channel_create / channel_delete
• chat_message (Channel or Server)
• permission_change

Configuration:

Webhooks are currently configured via the config.json on the server or through the API itself:

curl -X POST -H "x-api-key: ADMIN_KEY" \
     -d '{"url": "https://your-bot.com/ts-events", "events": ["*"]}' \
     "http://your-server:10080/v1/webhooks"

Best Practices

Troubleshooting the API