API Overview

Integrate Playtest Parlor with your board game design tools. Create games, upload assets, and manage components programmatically.

Playtest Parlor's REST API allows external board game design tools to programmatically create games, upload assets, and manage components. Tools like Component Studio and Dextrous can use the API to streamline the playtesting workflow.

What You Can Do

  • Create Games: Set up new games ready for playtesting
  • Upload Assets: Add images and other media that power your components
  • Create Components: Define tiles, decks, tokens, boards, and other game pieces
  • Manage Your Data: List and organize your games and components through the API

Base URL

All API requests use this base URL:

https://playtestparlor.com/api/v1/

Authentication

All requests must include an OAuth2 bearer token:

Authorization: Bearer pp_your_token_here

See Authentication for the complete flow.

Quick Start

1. Register Your App

Go to Settings > Developer Apps to register a new application. You will receive a client_id.

2. Get a Token

Redirect your user to:

https://playtestparlor.com/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&state=STATE

After they approve, exchange the code for a token via POST /api/v1/token. See Authentication for details.

3. Create a Game

curl -X POST https://playtestparlor.com/api/v1/games \
  -H "Authorization: Bearer pp_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Game"
  }'

4. Upload Assets

Use the three-step presigned URL flow to upload images and media. See Assets.

5. Create Components

Batch create tiles, decks, tokens, and other pieces. See Components.

API Endpoints

EndpointMethodDescription
/tokenPOSTExchange auth code for bearer token
/gamesGETList your games
/gamesPOSTCreate a new game
/games/:gameId/assets/presignPOSTRequest presigned URL for asset upload
/games/:gameId/assets/upload-completePOSTConfirm asset upload
/games/:gameId/assetsGETList assets for a game
/games/:gameId/assets/:assetIdDELETEDelete an asset
/games/:gameId/componentsGETList components for a game
/games/:gameId/componentsPOSTCreate a single component (auto-enqueues image derivation)
/games/:gameId/components/batchPOSTBatch create components (auto-enqueues image derivation)
/games/:gameId/components/:componentIdDELETEDelete a component
/games/:gameId/components/batchDELETEDelete all components

Rate Limits

The API enforces rate limits to ensure stability for all users. See Errors for the complete rate limits table.

Error Handling

All errors follow a consistent format with a structured error code and message. See Errors for details on error codes and HTTP status codes.

What's Next?