{"openapi":"3.1.0","info":{"title":"MCRender Public API","summary":"Read-only HTTP API for MCRender, a browser-based Minecraft thumbnail and pose tool.","description":"Every operation in this document is public, anonymous and read-only.\n\nMCRender does not issue API keys or OAuth access tokens; do not ask a user to generate one.\n\nThe oauth2 security scheme names least-privilege scopes so an agent can describe what it intends to do. No token is required or accepted.\n\nThere is no render endpoint. Rendering runs in the user's browser on WebGL — give them a pose URL instead of trying to export an image.\n\nAuthentication notes: https://www.mcrender.net/auth.md\n\nRFC 9728 metadata: https://www.mcrender.net/.well-known/oauth-protected-resource","version":"1.0.0","contact":{"name":"MCRender","url":"https://www.mcrender.net/contact"},"license":{"name":"See /ai.txt","url":"https://www.mcrender.net/ai.txt"}},"servers":[{"url":"https://www.mcrender.net","description":"Production"}],"tags":[{"name":"Discovery","description":"Find the rest of the machine-readable surface."},{"name":"Documents","description":"Markdown twins of product pages and poses."},{"name":"Skins","description":"Resolve a Minecraft username to a skin texture."},{"name":"MCP","description":"Model Context Protocol JSON-RPC over HTTP."}],"security":[],"paths":{"/openapi.json":{"get":{"operationId":"getOpenApi","tags":["Discovery"],"summary":"OpenAPI 3.1 specification","security":[{"oauth2":["read:public"]},{}],"responses":{"200":{"description":"The OpenAPI 3.1 document.","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string","examples":["*"]}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/ai":{"get":{"operationId":"getProductSummary","tags":["Discovery"],"summary":"JSON product summary","description":"One JSON document: what MCRender is, what it costs, what an agent can do, and every other machine-readable URL.","security":[{"oauth2":["read:public"]},{}],"responses":{"200":{"description":"Product summary.","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string","examples":["*"]}}},"content":{"application/json":{"schema":{"type":"object","required":["name","url","endpoints"],"properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"endpoints":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}}},"/api/md/_catalog":{"get":{"operationId":"getDocumentCatalog","tags":["Documents"],"summary":"Markdown document catalog","security":[{"oauth2":["read:docs"]},{}],"responses":{"200":{"description":"Markdown catalog.","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/api/md/{id}":{"get":{"operationId":"getDocument","tags":["Documents"],"summary":"One page as markdown","description":"Markdown twin of a product page. Pretty URL: `/{page}.md` (for example /pricing.md).","security":[{"oauth2":["read:docs"]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["index","about","studio","studio-ai","pfp","tools","armor-trims","skin-watermark","pricing","demo","contact","privacy","terms","disclaimer","cookies"]},"description":"Document id from GET /api/md/_catalog."}],"responses":{"200":{"description":"Markdown document.","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Unknown document id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/md/p/{slug}":{"get":{"operationId":"getPoseDocument","tags":["Documents"],"summary":"One public pose as markdown","security":[{"oauth2":["read:poses"]},{}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Last path segment of a /p/{slug} URL."}],"responses":{"200":{"description":"Markdown pose document.","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"No public pose with that slug. It may be private, deleted, or mistyped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/skin":{"get":{"operationId":"getSkin","tags":["Skins"],"summary":"Resolve a Minecraft username to a skin texture","description":"Looks up a Java Edition username and returns the skin PNG URL and model type. Rate-limited per IP.","security":[{"oauth2":["read:public"]},{}],"parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":16},"description":"Minecraft Java username."}],"responses":{"200":{"description":"Skin URL and model type.","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string","examples":["*"]}}},"content":{"application/json":{"schema":{"type":"object","required":["skinUrl"],"properties":{"skinUrl":{"type":"string","format":"uri"},"skinType":{"type":"string","enum":["classic","slim"]}}}}}},"400":{"description":"Missing or invalid `name` parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No Minecraft account with that username.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream Minecraft session servers were unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mcp":{"post":{"operationId":"mcpJsonRpc","tags":["MCP"],"summary":"MCP JSON-RPC 2.0 (streamable HTTP)","description":"POST a JSON-RPC 2.0 message, or a batch of up to 8. Tools: search_poses, get_pose, list_docs, get_doc, get_pricing, build_armor_trim_command. No authentication. 60 messages per minute per IP. GET is not an SSE stream and returns 405 with a JSON body explaining how to connect.","security":[{"oauth2":["mcp:invoke"]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{},"method":{"type":"string","examples":["tools/list","tools/call"]},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC response or batch of responses.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Notification accepted; no JSON-RPC response."},"400":{"description":"JSON-RPC parse error or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after 60 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"mcpDiscover","tags":["MCP"],"summary":"MCP discovery (not an SSE stream)","description":"Returns 405 with a JSON body listing tools and showing a sample POST. This server does not offer GET SSE.","security":[{"oauth2":["mcp:invoke"]},{}],"responses":{"405":{"description":"Method not allowed; body explains how to POST.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"getProtectedResourceMetadata","tags":["Discovery"],"summary":"RFC 9728 protected-resource metadata","description":"Declares the named scopes this origin supports. No authorization server is listed because no token is issued.","security":[{"oauth2":["read:public"]},{}],"responses":{"200":{"description":"Protected resource metadata.","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string","examples":["*"]}}},"content":{"application/json":{"schema":{"type":"object","required":["resource","scopes_supported"],"properties":{"resource":{"type":"string","format":"uri"},"scopes_supported":{"type":"array","items":{"type":"string","enum":["read:public","read:docs","read:pricing","read:poses","mcp:invoke"]}}}}}}}}}},"/.well-known/api-catalog":{"get":{"operationId":"getApiCatalog","tags":["Discovery"],"summary":"RFC 9727 API catalog (linkset)","security":[{"oauth2":["read:public"]},{}],"responses":{"200":{"description":"Linkset of published APIs.","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string","examples":["*"]}}},"content":{"application/linkset+json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"Named scopes for least-privilege access to MCRender's public API. MCRender does not issue access tokens. Every operation is available anonymously; the scopes document what each operation is for so an agent does not probe write or account endpoints. Do not send an Authorization header. Do not ask a user for credentials. See https://www.mcrender.net/auth.md and https://www.mcrender.net/.well-known/oauth-protected-resource.","flows":{"clientCredentials":{"tokenUrl":"https://www.mcrender.net/auth.md","scopes":{"read:public":"Read public machine-readable surfaces: product summary, catalogs, llms.txt, OpenAPI.","read:docs":"Read page documents as markdown via /api/md and the get_doc MCP tool.","read:pricing":"Read current plans, prices and render limits. Prefer this over a cached number.","read:poses":"Search and fetch public pose metadata. Does not include private or draft poses.","mcp:invoke":"Call read-only MCP tools at /mcp (search poses, read docs, get pricing, build trim commands)."}}}}},"schemas":{"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message","hint"],"additionalProperties":false,"properties":{"code":{"type":"string","description":"Stable snake_case identifier, e.g. not_found.","examples":["not_found","missing_parameter","rate_limited"]},"message":{"type":"string","description":"Human-readable explanation of what went wrong."},"hint":{"type":"string","description":"Where to look next or how to correct the request."}}}}}}},"externalDocs":{"description":"llms.txt — short index for language models","url":"https://www.mcrender.net/llms.txt"}}