Skip to main content

Getting started

Status: Current (Rack and Scale). This is the shortest path from Rack or Scale to a working /v1 call. The SDK quickstart is the code walkthrough. This page is the access, keys, and limits page.

1. Confirm you’re on Rack or Scale

The API key for whitelisting is included on Rack and Scale. Scale includes everything in Rack. Solo includes MCP and has no API key. There is nothing to toggle on. An active Rack or Scale plan is the entitlement. See Authentication.
Keep the org on Rack or Scale for as long as you call the API. A downgrade off those plans removes API access, including for a key minted earlier.

2. Mint a key and choose its scopes

Mint a wk_live_… key in the Developers tab of the Warmr app (or the web cockpit at app.warmr.so). Minting is a dashboard-only action an org owner or operator performs — an API session can never mint or revoke keys, so a leaked key can’t escalate itself into more keys. You see the raw key once; store it in a secret manager. Pick the scopes the key needs at mint time — a key never gains a scope it wasn’t minted with:
  • 9 default scopes cover runs, accounts, uploads, schedules, usage, and devices — enough to register an account, enqueue runs, and post clips.
  • 4 opt-in scopes (webhooks:read / webhooks:write, health:read, keys:read) are secret-bearing and must be requested explicitly.

3. Set the three deployment values

Every caller needs three deployment-specific values — there is no canonical public URL baked in:
https://app.warmr.so appears throughout these docs only as a placeholder — substitute your own deployment origin. Get these three wrong and the first call throws a WarmrAuthError.

4. Make your first call

With the SDK, the key → session exchange (and its caching and refresh) is handled for you:
To post a clip, follow the three-step upload flow (Content uploads) to get an upload_id, then enqueue a post run with it (Runs). Prefer raw HTTP? The exchange and Bearer flow are in Authentication.

5. Limits

Solo, Rack, and Scale include unlimited usage. The numbers below are request rate limits, and they are the same for every API caller. Rack and Scale are the plans that include the API key. Because a session token is reused until it nears expiry (the SDK caches and re-exchanges automatically), normal usage rarely approaches the exchange limits. Pace enqueues client-side off the RateLimit-* headers.

What the API can’t do (the airlock)

An API session enqueues and reads — it never drives a device. A server-side airlock enforces this:
  • It cannot claim a device or release a run a device already owns — acting on a claimed/running run returns 403 forbidden or 409 conflict.
  • It cannot set the target app over /v1 — the platform comes from your org’s account roster at dispatch, never from the caller.
  • It cannot mint or revoke keys — that is dashboard-only.
  • It cannot pass credentials or proxies — those secrets stay on your Mac (bring-your-own-fleet).
  • It cannot provision devices from the cloud — your own connected iPhones execute the work.

Next

  • Authentication — the exchange, token caching, and rate limits in detail.
  • Scopes — the full scope list and what each endpoint requires.
  • SDK quickstart — install @warmr/sdk and walk the full posting flow.
  • Runs — enqueue, batch, list, cancel, retry.