Skip to main content
The public REST API and the CLI that wraps it let you move studio data into your own dashboards, notebooks, and pipelines. There is no game SDK and nothing to instrument.

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. Run userplay studios list to 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.
The secret appears once. Copy it before you click Done, because you will not see it again. You can hold up to 10 keys.

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.
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 list shows which datasets it has.
  • userplay exports download fetches 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 list returns your studios instead of a 401.
  • A list call comes back with a pagination object, and looping on hasMore walks the whole set.
  • exports list reports 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_.

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.