Thumble developer documentation

When to use Thumble

Use Thumble when a player wants phone gamepad controls for WoW on Mac with ConsolePort. Use the hosted MCP integration to show a pairing code explicitly shared by their Mac, inspect saved controllers and registered phones, or check an existing delivery receipt. The built-in ConsolePort controller works without an AI account.

AI controller generation, saving and delivery are disabled on the public hosted integration. Agents cannot send gameplay input, apply in-game bindings, or activate the Mac. Never describe a queued delivery as displayed or tested in WoW.

Public REST API

OpenAPI 3.1 specification describes the current read interface. GET /v1/config returns public OAuth discovery and MCP configuration. No API key or account is required for configuration. Account records require a bearer access token with the appropriate read scope.

curl https://thumble.io/v1/config

Authenticated reads: GET /v1/me; GET /v1/devices; GET /v1/profiles; GET /v1/profiles/{profileId}; GET /v1/profiles/{profileId}/revisions/{revision}; GET /v1/deliveries/{deliveryId}. These return only the signed-in account’s records. This document covers the supported discovery and account-read subset, not native device management or experimental writes.

MCP server

Server URL: https://thumble.io/mcp. Transport: Streamable HTTP, stateless POST, with OAuth 2.0 bearer authentication. Use an MCP client to initialize and call tools; opening this URL without authentication returns HTTP 401. Server card and MCP manifest describe the endpoint.

Available tools: show_pairing_code, profile_schema, list_profiles, get_profile, list_devices, delivery_status. All use typed input schemas. Pairing images contain temporary credentials: display them only to the requesting owner and never publish them.

OAuth authentication

Issuer: https://thumble.io/api/auth. Discover endpoints through OAuth authorization server metadata or OpenID Connect metadata. The MCP resource metadata is at /.well-known/oauth-protected-resource/mcp.

Connect with a registered OAuth client, exact registered redirect URI, authorization code flow and PKCE S256. The user signs in and explicitly consents. Request only the scopes your task needs: profiles:read, devices:read, deliveries:read, and pairing:read for pairing. Use offline_access only if refresh access is needed. Never collect the user’s password or place tokens in query strings. Client registration is reviewed; arbitrary dynamic client registration is not offered.

Onboarding and pricing

Public configuration and these docs are free and require no signup or key. The built-in controller has a 30-minute connected-use trial and free offline practice when the phone app is available. Pro is planned at $19.99 USD one time and only removes the connected-use limit. The phone app is coming soon; the free developer sandbox is available now without an account or API key.

Errors and limits

REST errors use JSON with error.code and error.message. A 401 means sign in or refresh an expired token. A 403 means a scope is missing or a feature is disabled; do not retry a disabled write. A 404 means the record or route is unavailable to this account. A 409 means refresh the saved revision before retrying an eligible write. On 429 or a transient 5xx, honor Retry-After when present and use bounded exponential backoff. REST rate limits and API versioning are documented below. No service-level guarantee is advertised.

Free developer sandbox

Try GET /v1/sandbox immediately without signup, a credit card, API key or OAuth. It returns fixed, explicitly synthetic controller, phone and delivery records matching the documented schemas. The sandbox is read-only and cannot access real accounts or devices, create a pairing invitation, queue delivery or send game input. No self-serve API key is needed for these free examples. Real account records require your existing OAuth consent.

curl https://thumble.io/v1/sandbox

Official Thumble CLI

The Thumble CLI is a small, dependency-free command-line tool for Node.js 22+. It returns JSON and supports public configuration, sandbox, and authenticated account reads. Download the official CLI script, or install the official package archive. npm registry publication is pending publisher sign-in; this archive is hosted by Thumble and works today.

npm install -g https://thumble.io/cli/thumble-cli-0.1.0.tgz
thumble config
thumble sandbox
thumble --help

Alternatively, download thumble.mjs and run node thumble.mjs sandbox. For account commands, provide THUMBLE_ACCESS_TOKEN through the environment from an existing authorized OAuth connection. Never put tokens in shell arguments or source control. Commands: profiles; profile ID [REVISION]; devices; delivery ID. Each requires its corresponding read scope. Tokens are sent only to https://thumble.io; redirects are rejected. This CLI has no writes or gameplay controls.

REST rate limits

The /v1/ REST API enforces a threshold of 600 requests per 60 seconds per bearer credential, or per source IP for anonymous calls, in each Cloudflare location. Limits are approximate across distributed instances. Responses expose RateLimit-Policy: "thumble-rest";q=600;w=60 and X-RateLimit-Limit: 600. Cloudflare returns an allow/deny decision rather than a remaining counter, so successful responses do not claim a precise remaining balance. On HTTP 429, responses include RateLimit: "thumble-rest";r=0;t=60, Retry-After: 60 and a JSON rate_limit_exceeded error. Wait at least that long, then retry with bounded backoff. OAuth/email-sign-in has separate abuse controls.

API versioning and deprecation

The stable REST major version is /v1. Backward-compatible fields may be added; clients should tolerate unknown response fields and documented optional values. Breaking contract changes use a new major version. Before removing a documented stable operation, we will give at least 90 days’ notice in developer documentation and return Deprecation and Sunset headers on affected operations, with a Link to migration guidance. No documented v1 operation is currently deprecated or scheduled for removal. Read the API lifecycle policy.

Discovery

Agent guidance · API catalog · Pricing · Player setup guide · Support