Skip to main content
The TapKitClient is your main entry point for interacting with TapKit. It handles authentication, connection management, and provides access to your phones.

​
Basic Usage

from tapkit import TapKitClient

# Initialize with API key
client = TapKitClient(api_key="your-api-key")

# Or use environment variable TAPKIT_API_KEY
client = TapKitClient()

​
Configuration Options

client = TapKitClient(
    api_key="your-api-key",      # Your TapKit API key
    base_url="https://api.tapkit.ai",  # API endpoint (default)
    timeout=65.0                  # Request timeout in seconds (default: 65)
)
ParameterTypeDefaultDescription
api_keystr | NoneNoneYour API key. Falls back to TAPKIT_API_KEY env var
base_urlstr | Nonehttps://api.tapkit.aiAPI endpoint. Falls back to TAPKIT_BASE_URL env var
timeoutfloat65.0Request timeout in seconds

​
Context Manager

Use the client as a context manager for automatic cleanup: 
with TapKitClient() as client:
    phone = client.get_phone()
    phone.tap(phone.screen.center)
# Connection automatically closed
Or manually close when done: 
client = TapKitClient()
try:
    phone = client.get_phone()
    phone.tap(phone.screen.center)
finally:
    client.close()

​
System Status

Check the overall system status: 
status = client.status()

print(f"Mac app running: {status.mac_app_running}")
print(f"Phone connected: {status.phone_connected}")
print(f"Phone name: {status.phone_name}")
print(f"Switch Control enabled: {status.switch_control_enabled}")
print(f"Screen locked: {status.screen_locked}")
print(f"Streaming: {status.streaming}")

​
Status Fields

FieldTypeDescription
mac_app_runningboolWhether the Mac companion app is running
phone_connectedboolWhether a phone is connected
phone_namestr | NoneName of the connected phone
switch_control_enabledboolWhether Switch Control is enabled
screen_lockedboolWhether the device screen is locked
streamingboolWhether screen streaming is active

​
Client-Level Actions

You can execute actions directly on the client when you’ve set a default phone: 
client = TapKitClient()

# Set a default phone
client.use_phone("iPhone 15 Pro")

# Now call actions directly on client
client.tap((100, 200))
client.home()
screenshot = client.screenshot()
This is convenient when working with a single phone throughout your script.

​
Error Handling

The SDK raises TapKitError for API errors: 
from tapkit import TapKitClient, TapKitError

try:
    client = TapKitClient(api_key="invalid-key")
    phone = client.get_phone()
except TapKitError as e:
    print(f"TapKit error: {e}")

​
Next Steps

Managing Phones

Learn how to list and select phones

Screenshots

Capture screenshots from your phone