{ "openapi": "3.1.0", "info": { "title": "Playnix", "version": "1.0.0", "summary": "An arcade of small 2D games for children, open to agents.", "description": "Find a game, open it, or build one from a sentence and publish it.\n\nSearching, browsing and playing need no credentials. Building, liking and publishing need an account \u2014 either OAuth 2.1 with PKCE (see /.well-known/oauth-protected-resource) or a bearer token from POST /auth/login.\n\nThere is also an MCP server at POST /mcp and WebMCP tools on the page itself.", "license": { "name": "CC0-1.0", "url": "https://creativecommons.org/publicdomain/zero/1.0/" }, "contact": { "url": "https://playnix.dev" } }, "servers": [ { "url": "https://playnix.dev/api/gen", "description": "Production" } ], "externalDocs": { "url": "https://playnix.dev/agents.md", "description": "Playnix for agents" }, "tags": [ { "name": "Games", "description": "Find, open and rate games" }, { "name": "Categories", "description": "How the library is organised" }, { "name": "Building", "description": "Make a new game" }, { "name": "Accounts", "description": "Register and sign in" }, { "name": "Agents", "description": "MCP and service metadata" } ], "paths": { "/library": { "get": { "summary": "Browse the library", "description": "Every published game, filtered and sorted. Without `q` this is a plain browse.", "tags": [ "Games" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "genre": { "type": "string" }, "engine": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "author": { "type": "string", "description": "Owner id. Opaque \u2014 never render it." }, "authorName": { "type": "string", "description": "The name to show." }, "plays": { "type": "integer" }, "likes": { "type": "integer" }, "remixes": { "type": "integer" }, "multiplayer": { "type": "boolean" }, "featured": { "type": "boolean" }, "cover": { "type": "string", "description": "Relative URL of a real screenshot from the game." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "genre", "cover" ] } }, "total": { "type": "integer" } } } } } } }, "parameters": [ { "name": "q", "in": "query", "description": "Semantic search. Describe the game rather than guessing a title.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "One of the ids from GET /categories.", "schema": { "type": "string" } }, { "name": "genre", "in": "query", "description": "An engine genre such as pacman, runjump, bomb, brawl.", "schema": { "type": "string" } }, { "name": "multiplayer", "in": "query", "description": "true for two-or-more-player games only.", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "description": "recent (default), popular, remixed or az.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "1-500, default 50.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "Page offset.", "schema": { "type": "integer" } } ] } }, "/search": { "get": { "summary": "Search games", "description": "Semantic search. 'A game where I dig holes to trap enemies' finds the Lode Runner one.", "tags": [ "Games" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "genre": { "type": "string" }, "engine": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "author": { "type": "string", "description": "Owner id. Opaque \u2014 never render it." }, "authorName": { "type": "string", "description": "The name to show." }, "plays": { "type": "integer" }, "likes": { "type": "integer" }, "remixes": { "type": "integer" }, "multiplayer": { "type": "boolean" }, "featured": { "type": "boolean" }, "cover": { "type": "string", "description": "Relative URL of a real screenshot from the game." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "genre", "cover" ] } } } } } } } }, "parameters": [ { "name": "q", "in": "query", "description": "What the player is in the mood for, in plain language.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "1-500.", "schema": { "type": "integer" } } ] } }, "/categories": { "get": { "summary": "List categories", "description": "The categories games are filed under, each with a count and the genres inside it. Use this before searching blind.", "tags": [ "Categories" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "blurb": { "type": "string" }, "count": { "type": "integer" }, "genres": { "type": "array", "items": { "type": "string" } }, "examples": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "genre": { "type": "string" }, "engine": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "author": { "type": "string", "description": "Owner id. Opaque \u2014 never render it." }, "authorName": { "type": "string", "description": "The name to show." }, "plays": { "type": "integer" }, "likes": { "type": "integer" }, "remixes": { "type": "integer" }, "multiplayer": { "type": "boolean" }, "featured": { "type": "boolean" }, "cover": { "type": "string", "description": "Relative URL of a real screenshot from the game." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "genre", "cover" ] } } } } } } } } } } } } }, "/games/{id}": { "get": { "summary": "One game", "description": "The full record including the spec that runs it.", "tags": [ "Games" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "genre": { "type": "string" }, "engine": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "author": { "type": "string", "description": "Owner id. Opaque \u2014 never render it." }, "authorName": { "type": "string", "description": "The name to show." }, "plays": { "type": "integer" }, "likes": { "type": "integer" }, "remixes": { "type": "integer" }, "multiplayer": { "type": "boolean" }, "featured": { "type": "boolean" }, "cover": { "type": "string", "description": "Relative URL of a real screenshot from the game." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "genre", "cover" ] } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id", "schema": { "type": "string" } } ] } }, "/games/{id}/similar": { "get": { "summary": "Games like this one", "description": "Nearest neighbours in the same semantic index.", "tags": [ "Games" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id", "schema": { "type": "string" } } ] } }, "/games/{id}/remixes": { "get": { "summary": "Remixes of this game", "description": "Direct descendants.", "tags": [ "Games" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id", "schema": { "type": "string" } } ] } }, "/games/{id}/play": { "post": { "summary": "Count a play", "description": "Records that the game was opened.", "tags": [ "Games" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id", "schema": { "type": "string" } } ] } }, "/games/{id}/like": { "post": { "summary": "Like a game", "description": "Likes are what push good games up the library.", "tags": [ "Games" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Not signed in" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Game id", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "games:write" ] } ] } }, "/engines": { "get": { "summary": "List engines", "description": "The 2D libraries a game can be built on, and what each is good at.", "tags": [ "Games" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/stats": { "get": { "summary": "Library stats", "description": "Counts of games, genres, engines and art.", "tags": [ "Games" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/health": { "get": { "summary": "Health", "description": "Whether generation is reachable, and which model is answering.", "tags": [ "Agents" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/generate-code-staged": { "post": { "summary": "Build a game", "tags": [ "Building" ], "description": "Starts a build and streams its progress as Server-Sent Events. Generation takes minutes, so this is a job, not a request: the stream can be dropped and re-attached at /build/{id}/stream.\n\nAgents should prefer the MCP tool `build_game`, which returns a build id immediately.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "games:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string" }, "build": { "type": "object" } }, "required": [ "prompt" ] } } } }, "responses": { "200": { "description": "SSE stream", "content": { "text/event-stream": {} } }, "429": { "description": "Rate limited: 6 builds an hour for a guest, 30 signed in." } } } }, "/build/{id}": { "get": { "summary": "Build status", "description": "Cheap to poll.", "tags": [ "Building" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Build id", "schema": { "type": "string" } } ] } }, "/publish": { "post": { "summary": "Publish a game", "tags": [ "Building" ], "description": "Adds or updates a game in the public library. Ownership comes from the token, not the body.", "security": [ { "bearerAuth": [] }, { "oauth2": [ "games:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string" }, "spec": { "type": "object" } }, "required": [ "prompt", "spec" ] } } } }, "responses": { "200": { "description": "Published" }, "400": { "description": "Spec failed validation" } } } }, "/my/games": { "get": { "summary": "My games", "description": "Everything on this account, published or not.", "tags": [ "Accounts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Not signed in" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "games:write" ] } ] } }, "/auth/register": { "post": { "summary": "Create an account", "tags": [ "Accounts" ], "description": "A name and a 4-8 digit PIN, or an email and a PIN. Five wrong tries locks the account for 15 minutes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "pin": { "type": "string" } }, "required": [ "pin" ] } } } }, "responses": { "200": { "description": "Account and session token" }, "400": { "description": "Name taken, or a weak PIN" } } } }, "/auth/login": { "post": { "summary": "Sign in", "tags": [ "Accounts" ], "description": "Returns an opaque, revocable session token. Send it as Authorization: Bearer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "pin": { "type": "string" } }, "required": [ "pin" ] } } } }, "responses": { "200": { "description": "Session token" }, "401": { "description": "Wrong name or PIN" } } } }, "/auth/me": { "get": { "summary": "Who am I", "description": "The account behind the current token.", "tags": [ "Accounts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Not signed in" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "games:write" ] } ] } }, "/auth/logout": { "post": { "summary": "Sign out", "description": "Revokes this token server-side.", "tags": [ "Accounts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Not signed in" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "games:write" ] } ] } }, "/mcp": { "post": { "summary": "MCP endpoint", "tags": [ "Agents" ], "description": "Model Context Protocol over Streamable HTTP, stateless. POST one JSON-RPC request, get one JSON response. 13 tools. Reading is anonymous; building and publishing need a token.\n\nSee /.well-known/mcp/server-card.json.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": {}, "method": { "type": "string" }, "params": { "type": "object" } }, "required": [ "jsonrpc", "method" ] } } } }, "responses": { "200": { "description": "JSON-RPC response" }, "202": { "description": "Notification accepted" }, "405": { "description": "Stateless server; use POST" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A session token from POST /auth/login." }, "oauth2": { "type": "oauth2", "description": "Authorization Code with PKCE.", "flows": { "authorizationCode": { "authorizationUrl": "https://playnix.dev/api/gen/oauth/authorize", "tokenUrl": "https://playnix.dev/api/gen/oauth/token", "scopes": { "games:read": "Search, browse and open games", "games:write": "Build and publish games" } } } } }, "schemas": { "GameSummary": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "genre": { "type": "string" }, "engine": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "author": { "type": "string", "description": "Owner id. Opaque \u2014 never render it." }, "authorName": { "type": "string", "description": "The name to show." }, "plays": { "type": "integer" }, "likes": { "type": "integer" }, "remixes": { "type": "integer" }, "multiplayer": { "type": "boolean" }, "featured": { "type": "boolean" }, "cover": { "type": "string", "description": "Relative URL of a real screenshot from the game." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "genre", "cover" ] } } }, "security": [ {} ] }