{ "openapi": "3.1.0", "info": { "title": "PyroSoft public content API", "version": "1.0.0", "description": "Read-only public catalog, writing and MCP tools. Product queries match all terms in public text. No account, customer, payment or admin operations." }, "servers": [ { "url": "https://pyrosoft.pro" } ], "security": [], "paths": { "/api/v1/catalog.json": { "get": { "operationId": "list_products", "summary": "List public products", "parameters": [ { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "enum": [ "software", "soon", "legacy" ] } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "price", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "enum": [ "free", "paid", "pwyw" ] } } ], "responses": { "200": { "description": "Public content only; no cookies or account state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "products", "count" ], "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "count": { "type": "integer", "minimum": 0 } } } } } }, "400": { "description": "Public content only; no cookies or account state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "head": { "summary": "Headers for this public listing", "parameters": [ { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "enum": [ "software", "soon", "legacy" ] } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "price", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "enum": [ "free", "paid", "pwyw" ] } } ], "responses": { "200": { "description": "Same headers as GET, without a body." } } }, "options": { "summary": "Public read-only CORS preflight", "responses": { "204": { "description": "GET, HEAD and OPTIONS are allowed." } } } }, "/api/v1/blog.json": { "get": { "operationId": "list_posts", "summary": "List public posts", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "series", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "product", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Public content only; no cookies or account state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "posts", "count" ], "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "count": { "type": "integer", "minimum": 0 } } } } } }, "400": { "description": "Public content only; no cookies or account state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "head": { "summary": "Headers for this public listing", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "series", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "product", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Same headers as GET, without a body." } } }, "options": { "summary": "Public read-only CORS preflight", "responses": { "204": { "description": "GET, HEAD and OPTIONS are allowed." } } } }, "/api/v1/software/{slug}.json": { "get": { "operationId": "get_product", "summary": "Read one public product", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,127}$" } } ], "responses": { "200": { "description": "Public content only; no cookies or account state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/Product" } } } } } }, "404": { "description": "Public content only; no cookies or account state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "head": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,127}$" } } ], "responses": { "200": { "description": "Same headers as GET, without a body." }, "404": { "description": "Unknown slug." } } }, "options": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,127}$" } } ], "responses": { "204": { "description": "Public read-only CORS preflight." } } } }, "/api/v1/blog/{slug}.json": { "get": { "operationId": "get_post", "summary": "Read one public post", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,127}$" } } ], "responses": { "200": { "description": "Public content only; no cookies or account state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "post" ], "properties": { "post": { "$ref": "#/components/schemas/Post" } } } } } }, "404": { "description": "Public content only; no cookies or account state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "head": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,127}$" } } ], "responses": { "200": { "description": "Same headers as GET, without a body." }, "404": { "description": "Unknown slug." } } }, "options": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,127}$" } } ], "responses": { "204": { "description": "Public read-only CORS preflight." } } } }, "/mcp": { "post": { "operationId": "read_public_content_mcp", "summary": "Read public content through MCP; no account or purchase actions", "description": "Streamable HTTP JSON responses. Supports 2026-07-28 per-request metadata and 2025-11-25/2025-06-18 initialization. Modern calls require matching MCP-Protocol-Version, Mcp-Method and, where applicable, Mcp-Name headers. Modern params._meta carries protocolVersion and clientCapabilities under io.modelcontextprotocol/. Origin and Host are checked. No SSE stream or session id; GET/DELETE return 405. Public read-only tools only.", "parameters": [ { "name": "MCP-Protocol-Version", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "Mcp-Method", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "Mcp-Name", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "integer", "string" ] }, "method": { "type": "string", "maxLength": 128 }, "params": { "type": "object" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "JSON-RPC result; public content only.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed parameters, version or headers.", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Host or Origin refused.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown modern RPC method.", "content": { "application/json": { "schema": { "type": "object" } } } }, "406": { "description": "Accept must include JSON and event-stream.", "content": { "application/json": { "schema": { "type": "object" } } } }, "413": { "description": "Body exceeds 64 KiB.", "content": { "application/json": { "schema": { "type": "object" } } } }, "415": { "description": "Content type must be JSON.", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Public request/tool quota reached.", "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "description": "Content temporarily unavailable.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted legacy notification; no response body." } } } } }, "components": { "schemas": { "Product": { "type": "object", "required": [ "slug", "name", "status", "url", "legacy", "price" ], "additionalProperties": false, "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "kind": { "type": "string" }, "section": { "type": "string" }, "url": { "type": "string" }, "tagline": { "type": "string" }, "description": { "type": "string" }, "markdown_url": { "type": "string" }, "requirements": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "license_note": { "type": [ "string", "null" ] }, "device_limit": { "type": [ "string", "null" ] }, "availability_note": { "type": [ "string", "null" ] }, "platforms": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "array", "items": { "type": "string" } }, "features": { "type": "array", "items": { "type": "string" } }, "legacy": { "type": "boolean" }, "free": { "type": "boolean" }, "direct_checkout": { "type": "boolean" }, "noindex": { "type": "boolean" }, "price": { "type": "object", "required": [ "display", "model", "amount_usd" ], "additionalProperties": false, "properties": { "display": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "amount_usd": { "type": [ "string", "null" ] } } }, "links": { "type": "array", "items": { "type": "object", "required": [ "label", "url" ], "additionalProperties": false, "properties": { "label": { "type": "string" }, "url": { "type": "string", "format": "uri-reference" } } } }, "screenshots": { "type": "array", "items": { "type": "object", "required": [ "url", "alt" ], "properties": { "url": { "type": "string" }, "alt": { "type": "string" } }, "additionalProperties": false } }, "faq": { "type": "array", "items": { "type": "object", "required": [ "question", "answer" ], "properties": { "question": { "type": "string" }, "answer": { "type": "string" } }, "additionalProperties": false } }, "facts": { "type": "object" }, "course": { "type": "object" } } }, "Post": { "type": "object", "required": [ "slug", "title", "url", "kind", "markdown_url" ], "additionalProperties": false, "properties": { "slug": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "stand": { "type": "string" }, "url": { "type": "string" }, "markdown_url": { "type": "string" }, "content_markdown": { "type": "string" }, "date_published": { "type": "string" }, "disclosure": { "type": "string" }, "author": { "type": "string" }, "date_kind": { "type": "string" }, "work_start": { "type": "string" }, "work_end": { "type": "string" }, "updated": { "type": "string" }, "read": { "type": [ "integer", "string" ] }, "product": { "type": [ "string", "null" ] }, "cover": { "type": [ "string", "null" ] }, "series": { "type": "object" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }