Developer API

Early Access

Kineticist API

REST API, command-line tool, and MCP server for AI agents. 1,700+ games with edition pricing, design team credits, images, OPDB cross-references, and community ratings.

Quick Start

1. Sign in to your Kineticist account (or create one)
2. Go to Settings and create an API key
3. Make your first request:

curl -H "Authorization: Bearer ki_live_YOUR_KEY" \
https://www.kineticist.com/api/v1/games/random

For interactive try-it-out docs, see the API Reference. Download the OpenAPI spec.

Authentication

All requests require an API key sent as a Bearer token in the Authorization header:

Authorization: Bearer ki_live_YOUR_KEY

Keys are free. You can create up to 3 active keys in Settings.

Rate Limits

Window	Limit
Per second (burst)	10 requests
Per minute	60 requests
Per day	1,000 requests (resets midnight UTC)

Every response includes rate limit headers: X-RateLimit-Remaining-Day, X-RateLimit-Remaining-Minute, and X-RateLimit-Reset.

Endpoints

GET

/api/v1/games

List games with filtering, sorting, and pagination

GET

/api/v1/games/:id_or_slug

Get a game by slug, UUID, or OPDB ID. Editions always included.

GET

/api/v1/games/:id_or_slug/credits

Design team credits

GET

/api/v1/games/:id_or_slug/tags

Game tags

GET

/api/v1/games/:id_or_slug/trims

Editions/trims (also on detail)

GET

/api/v1/games/random

Random game with full detail

GET

/api/v1/games/batch?ids=...

Up to 50 games by ID

GET

/api/v1/stats

Database statistics

Full request/response examples for every endpoint in the interactive API reference.

Games & Editions

Pinball games often ship in multiple editions — Pro, Premium, LE, etc. In the Kineticist database, a game is the parent title (e.g. "Godzilla") and editions are the variants (Pro, Premium, LE, 70th Anniversary). Each edition has its own MSRP, production run, and specs.

Editions are always included on game detail responses — no extra request needed. Pricing lives on editions, not on the game itself. List responses include an editions_count field so you can see at a glance which games have multiple variants.

There are no separate pages for editions. If someone searches for "Godzilla Premium", direct them to the parent game (/api/v1/games/godzilla-2021) and find the Premium edition in the editions array.

Filtering & Sorting

The /api/v1/games endpoint supports these query parameters:

Parameter	Description
`manufacturer`	Filter by manufacturer slug or name (fuzzy match, e.g. `stern`). Only matches game manufacturers, not mod-only companies.
`in_production`	`true` or `false`
`year_from` / `year_to`	Filter by manufacture year range
`game_type`	Filter by type (e.g. `solid_state`)
`q`	Text search by game name (fuzzy, 2+ characters)
`sort`	Sort field. Prefix with `-` for descending. Options: `name`, `first_manufacture_year`, `average_fun_score`, `ratings_count`
`limit`	Results per page (1-100, default 25)
`offset`	Skip N results (max 10,000)
`fields`	Comma-separated fields for sparse responses (e.g. `name,slug,average_fun_score`)
`include`	Inline optional sub-resources on detail: `credits` (editions and tags are always included)

Response Format

Single Resource

Every game response includes a prefixed id, the game data, and links to related resources and the web page on kineticist.com.

List

List responses include editions_count so you know how many editions (Pro, Premium, LE, etc.) a game has without fetching the detail. Pagination links are included for easy traversal.

Errors

{
  "error": {
    "type": "rate_limit_error",
    "code": "daily_limit_exceeded",
    "message": "Daily request limit of 1,000 exceeded. Resets at midnight UTC.",
    "hint": "You're tilting! Step away from the machine and come back tomorrow.",
    "doc_url": "https://www.kineticist.com/docs/api/errors#daily_limit_exceeded"
  }
}

Error types: invalid_request_error, authentication_error, rate_limit_error, not_found_error, api_error

Object IDs

All IDs are type-prefixed UUIDs. You can pass either the prefixed or raw UUID — both work. Responses always include the prefix.

Type	Prefix	Example
Game	`gm_`	gm_550e8400-e29b-...
Manufacturer	`mfr_`	mfr_7c9e6679-...
Person	`prs_`	prs_a1b2c3d4-...
Tag	`tag_`	tag_f2a3b4c5-...
Edition	`trm_`	trm_e0f1a2b3-...

Example Queries

Stern games currently in production

GET /api/v1/games?manufacturer=stern&in_production=true

Highest rated games of the 90s

GET /api/v1/games?year_from=1990&year_to=1999&sort=-average_fun_score

Search for a game

GET /api/v1/games?q=medieval+madness

Get a random game with full details

GET /api/v1/games/random

Get a game with design credits in one call

GET /api/v1/games/medieval-madness?include=credits

Look up a game by OPDB ID

GET /api/v1/games/GweeP-MW95j

Works with both OPDB group IDs (weeP) and full machine IDs (GweeP-MW95j). Machine IDs resolve to the parent game.

CLI

Query the Kineticist database from your terminal. Zero dependencies.

$ export KINETICIST_API_KEY=ki_live_...

$ pinball random
$ pinball search "medieval madness"
$ pinball get godzilla-2021
$ pinball list -m stern -p
$ pinball credits godzilla-2021
$ pinball stats

Command	Description
`random`	Get a random game with full details and credits
`get <slug\|opdb_id>`	Get full game details by slug or OPDB ID
`search <query>`	Search for games by name
`list [options]`	List games with filters: `-m` manufacturer, `-p` in production, `--from/--to` year range, `-s` sort
`credits <slug>`	Show design team credits
`stats`	Database statistics

Install globally:

npm install -g @kineticist/cli

MCP Server (AI Agents)

Connect the Kineticist database to AI agents like Claude, ChatGPT, Cursor, and other tools that support the Model Context Protocol. The MCP server exposes 5 tools that agents can call natively.

Tool	Description
`search_pinball_games`	Search and filter games with natural language
`get_game_details`	Full game info with editions, images, and description
`get_game_credits`	Design team for a game
`get_random_game`	Random game for discovery
`get_pinball_stats`	Database statistics

Add to Claude Code / Cursor

// claude_desktop_config.json or .cursor/mcp.json { "mcpServers": { "kineticist": { "command": "npx", "args": ["@kineticist/mcp-server"], "env": { "KINETICIST_API_KEY": "ki_live_YOUR_KEY" } } } }

Once configured, your AI agent can answer questions like "What Stern games are in production?" or "Who designed Medieval Madness?" using live Kineticist data.

Terms of Use & Attribution

By using the Kineticist API you agree to the following:

Attribution Required

Any application, website, or service that displays Kineticist data to end users must include visible attribution with a link back to kineticist.com. Use one of these formats:

Data provided by Kineticist

Attribution must be visible on every page or screen that displays Kineticist data. Footer placement is fine. Hidden or invisible attribution does not count.

Permitted Uses

- Building apps, tools, or websites that reference pinball game data
- Tournament software, collection trackers, and community tools
- Editorial and journalistic use with attribution
- Academic research and personal projects

Please don't

- Scrape the entire database to build a competing product
- Remove or hide the attribution link

We reserve the right to revoke API keys that violate these terms.

Ready to build?

Free during early access. Create your API key and start querying in under 5 minutes.

Get Your API Key

Feedback? Requests? Let Colin know.