What you need first
- A Userplay account with a role in the studio you want to read. A key inherits your permissions, so it can do exactly what you can do and nothing more.
- Node 20 or later, if you want the CLI instead of raw HTTP.
- Your
studioId, which almost every endpoint takes as its first path segment. Runuserplay studios listto get it.
The playbook
1
Create an access key
Go to Account > Developer and find the Access keys section.
- Click Create access key.
- Give it a name, then click Create key.
- Copy the secret from the Save your access key screen.
- Click Done.
API keys
Rotating, deactivating, and deleting a key you already made.
Public API
What the API covers before you spend a key on it.
2
Call the API
Send a Bearer token against
https://api.userplay.io/public/v1.- curl
- CLI
Every response wraps its payload in a
data envelope. The CLI is generated from the same route definitions, so anything you can do in one you can do in the other.API quickstart
Three calls: your studios, a studio’s playtests, then its sessions.
CLI command reference
Every command, argument, and flag.
3
Page through the lists
Pass
page, perPage, and sortOrder to any list endpoint, then loop until pagination.hasMore is false.Pagination
Walking a long list without missing a page.
Global options
Agent mode, JSON output, dry runs, and write guards.
4
Handle the rate limit
Back off and retry when a request returns
429 instead of data.Each key gets its own request budget.
5
Pull your results out
Run the two export commands against a playtest.
userplay exports listshows which datasets it has.userplay exports downloadfetches one.
Playtest-scope datasets download directly. Session-scope files resolve to a signed link that expires, so save the file and discard the URL.
Exports
Every export command, argument, and flag.
Export your playtest data
Playbook: the same datasets, taken from the studio instead.
What the API cannot do
The API is read-first. It also writes the things you need to set up a playtest: drafts, players, groups, vaults, keys, rosters. But it never acts on your behalf in front of a player.Rotating a key invalidates the old secret immediately. Deactivating one makes every request with it return
401, and you can reactivate it later. Deleting one cannot be undone, and the studio makes you type the key’s name to confirm.How you know it worked
userplay studios listreturns your studios instead of a401.- A list call comes back with a
paginationobject, and looping onhasMorewalks the whole set. exports listreports a dataset as available, meaning the artifact behind it finished processing.- Under Account > Developer, the key’s row shows a Status of Active and a masked value starting with
up_.
Related articles
Authentication
Creating a key, sending it, and why a valid key can still be refused.
Rate limits
The per-key budget, and the backoff loop for a 429.
Errors
Every status code the API returns and what to do about each one.
Pagination
Walking a long list without missing a page.
Set up a playtest from the command line
Build a draft from the CLI, then publish it in the studio.
Exports
Every dataset, and which are playtest-scope versus session-scope.