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.

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:

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

Tiers & Rate Limits

Every key belongs to one of three tiers. All tiers are free during early access — the tier labels just set the ceiling. New keys start on free.

Daily limits reset at midnight UTC. Every response includes rate limit headers: X-RateLimit-Tier, X-RateLimit-Remaining-Day, X-RateLimit-Remaining-Minute, and X-RateLimit-Reset.

Need a higher ceiling? Email colin@kineticist.com with a short note about what you're building. Upgrades are free during early access.

Endpoints

Read endpoints return public game data. Write endpoints act on the API key owner's own library (play logs, ownership, wishlist, fun scores).

Read

Your library

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. Where available, editions also include manufacture_date, model_number, and mpu (CPU board type).

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:

Response Format

Game Detail

{
  "object": "game",
  "id": "gm_44587386-0321-5463-89a6-0df400c1c7d4",
  "data": {
    "name": "Godzilla",
    "slug": "godzilla-2021",
    "first_manufacture_year": 2021,
    "in_production": true,
    "average_fun_score": 89,
    "ratings_count": 81,
    "manufacturer": { "id": "mfr_...", "name": "Stern Pinball Inc.", "slug": "stern-pinball-inc" },
    "editions_count": 4,
    "editions": [
      { "id": "trm_...", "name": "Godzilla (Pro)", "trim_level": "Pro", "msrp": "6899", ... }
    ],
    "tags": [ { "id": "tag_...", "name": "Licensed", "slug": "licensed" } ],
    "images": { "flyers": [...], "tutorial": [...], "other": [...] }
  },
  "links": {
    "self": "/api/v1/games/godzilla-2021",
    "credits": "/api/v1/games/godzilla-2021/credits",
    "web": "https://www.kineticist.com/games/pinball/godzilla-2021"
  }
}

List responses return the same fields minus editions, tags, and images, but include editions_count and pagination links.

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.

Example Queries

Files

ROMs, service manuals, schematics, parts lists, and instruction cards. List files for a specific game, browse all files across the catalog, or get a signed download URL. Downloads require authentication. Signed URLs expire after 5 minutes.

List files for a game

Filter by format (zip, bin, pdf, txt) or file_type (rom, parts_list, manual, schematic, instruction_card). Supports standard limit/offset pagination.

Download a file

{
  "object": "file_download",
  "id": "fil_a1b2c3d4-...",
  "data": {
    "name": "Revision L-5 Game ROM",
    "format": "zip",
    "size_bytes": 199384,
    "download_url": "https://...",
    "expires_in": 300
  }
}

Pass ?redirect=true for a 302 redirect to the download URL instead of JSON — useful for direct browser downloads.

Browse all files

Sorted by download count (most popular first). Each file includes a nested game object with the parent game's name, slug, and year. Filter by game (slug), format, file_type, year_from, and year_to.

Your Library

Read and write the API key owner's own game data — play logs, ownership, wishlist, fun scores, favorites. The CLI and MCP server wrap these same endpoints.

Read your state for a game

{
  "gameId": "44587386-0321-5463-89a6-0df400c1c7d4",
  "owned": true,
  "wantToPlay": false,
  "wantToOwn": false,
  "favorite": true,
  "playCount": 12,
  "latestPlayAt": "2026-04-12",
  "funScore": 87
}

Pass the raw UUID (without the gm_ prefix). Agents typically call this after a write to verify the mutation landed.

Write actions

All writes go through one endpoint. Pick a handler and send its fields in the same JSON body.

{
  "handler": "logPlay",
  "gameId": "44587386-0321-5463-89a6-0df400c1c7d4",
  "playedAt": "2026-04-17",
  "locationText": "Pin Museum",
  "note": "cleared wizard mode",
  "score": 2350000
}

Writes are available on every tier. They count against the same daily quota as reads, so heavy batch imports will burn through a free key quickly — email colin@kineticist.com if you need a higher ceiling.

CLI

Query the Kineticist database and track your own games from your terminal. Zero dependencies.

Read commands

Track your games

Install globally:

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 11 tools — 5 for reading the public database and 6 for acting on the key owner's own library.

Read tools

Your library tools

Add to Claude Code / Cursor

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

Images

Image URLs returned by the API (e.g. image_url, editions[].image_url) point directly to media.kineticist.com and can be hotlinked, embedded, or displayed in your application.

For heavy usage, we recommend caching images locally or behind your own CDN to keep your app fast and avoid unnecessary bandwidth on both sides.

Terms of Use & Attribution

By using the Kineticist API you agree to the following:

Don't scrape the full database to build a competing product or strip the attribution link. We reserve the right to revoke keys that violate these terms.